Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
HI-ASM Motorola 68K Assembler © Copyright 1998 HIWARE HI-ASM © Copyright 1998 HIWARE HI-ASM 3 Contents Motorola 68K Assembler . . . . . . . . . . . . . . . . . . . . . . . . 5 User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Interactive User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Macro Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Output Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Implementation Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Assembler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Defining Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Mixing C and Assembler Applications . . . . . . . . . . . . . . . . . . . . . 29 References to External Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Building Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Assembler Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Mixed C and Assembler Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Memory Maps and Segmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 © Copyright 1998 HIWARE HI-ASM 4 © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 5 Motorola 68K Assembler This chapter describes the macro assembler. All assemblers of the HI-ASM family consist of a front end which is target independent and a back end which is target dependent. It is also documented in this chapter, how to mix C and assembler applications. For the instruction set supported by the assembler refer to the Reference Manual of the CPU used. User Interface Interactive User Interface The HI-ASM assembler only runs under Windows 3.1, it can't be run under plain MS-DOS. Starting from the Program Manager To start the assembler from the Windows Program Manager, double click its icon. The assembler opens a window and prompts for a file name. After you have entered the name of the file you want to assemble, the assembler processes the file and then prompts again for a file name. To leave the assembler, either hit the escape-key (ESC) or Alt-F4 or select the menu entry Close in the assembler's window menu. With the F3 key the last command can be displayed again and edited. If an error occurs during assembly, the assembler prints the first error message on the screen and also produces a file containing all errors found. The assembler only displays warnings, information messages and the first error on the screen, but the error file contains all messages produced. Starting from WinEdit or Codewright If you use WinEdit or Codewright and start the assembler directly from the editor, the user interface is slightly different. The assembler does not open its window. The mouse cursor is changed to the icon of WinEdit’s Compile button for the duration of the assembly. If the assembler has found an error, a single beep is emitted. All errors detected can be viewed with © Copyright 1998 HIWARE HI-ASM 6 User Interface WinEdit’s Search Error and Next Error or Codewright’s Find Next Error menu entries . If no error is found, the file is assembled. Assembly is done when the mouse cursor changes back to the normal arrow. Note: When WinEdit 3.0g is used, the following line has to be included in WinEdit's (WINEDIT.INI) initialization files: OUTPUT=.\EDOUT Batch Interface The assembler also provides a batch interface, which is used when starting it from WinEdit or the Make Utility, i.e. all file names and options may also be given on the command line instead of at the prompt in the assembler’s window. Command Line Options Like the compiler, the HI-ASM macro assembler accepts a variety of command line option switches. These switches follow the usual syntax for options, i.e. they all start with a dash ("–") followed by the option. Anything not starting with a dash is supposed to be the name of a source file to be translated. –H The help option prints a short summary of the options available. –L Writes a list file to the file having the same name as the source file but with extension .LST. –Lc –Ld –Le –Li Macro calls are not listed. Macro definitions are not listed. Macro expansions are not listed until the first redefinition with MLIST (see below). Include files are not listed. –M This option controls the memory model the assembler is to generate code for. This option is only of importance, if the assembler is used together with the compiler. The following possibilities exist: –Ml –Mm –Mm* –Ms LARGE memory model. MEDIUM memory model (all data must fit into the range -32k to +32k. As “–Mm”, but object pointers are only 2 bytes wide. SMALL memory model (code and data together must fit into the range 32k to +32k. –Ms* As “–Ms”, but all pointers are only 2 bytes wide. © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 7 For more details about memory models, please see chapter Compiler. –N Makes the assembler display an alert box if there was an error during compilation. This is useful when running a makefile since the assembler waits for the user to acknowledge the message, thus suspending makefile processing. (The 'N' stands for "Notify".) –P Used to specify code generation for a specific processor of the M68k family. The following possibilities exist: –Pmc10 Support 68010 instruction set. –Pmc20 Support 68020 instruction set. –Pmc30 Support 68030 instruction set. –Pmc40 Support 68040 instruction set. –Pmc32 Support CPU32 instruction set. –Pmc81 Generate code for a floating point unit (MC68881 or the FPU of a MC68040). –V This option prints the assembler version. –W This option controls the assembler's error output. There are two levels of verbosity: –W1 –W2 Inhibits the assembler’s printing INFORMATION messages, only WARNINGs and ERROR messages are output. Suppresses all messages of type INFORMATION and WARNING, only ERRORs are printed. Command line options are not case sensitive, e.g. "–Li" is the same as "–li". To facilitate the specification of several options belonging to the same group, e.g. "– Lc" and "–Li", the assembler allows coalescing options in the same group, i.e. one might also write "–Lci" or "–Lic" instead of "–Lc –Li". Note: It is not possible to coalesce options in different groups, e.g. "–Lc –W1" cannot be abbreviated by the options "–Lc1" or "–LcW1"! ASMOPTIONS If this environment variable is set, the assembler appends its contents to its command line each time a file is assembled. It can be used to globally specify certain options that should always be set, so you don’t have to specify them at every compilation (please see document Appendix, section Environment). © Copyright 1998 HIWARE HI-ASM 8 Macro Assembler Macro Assembler Input Files Source Files The front end takes any file as input, it doesn't require the filename to have a special extension. Include Files Include files must be written in assembler, not in C. The search for include files is governed by the two environment variables GENPATH and LIBPATH (please see document Appendix, section Environment). Include files that are included using double quotes as in INCLUDE "test.h" are searched for first in the current directory, then in the directories given in the environment variable GENPATH and finally in those given in LIBPATH. Output Files Object Files After successful assembly, the assembler generates an object file containing the target code as well as some debugging information. The assembler normally puts object files in the first directory in environment variable OBJPATH. If that variable is not set, the object file is written into the directory the source file was found. These object files are compatible with object files generated by the compiler. Object files always get the extension .o. Debug Listing The assembler generates a source file for the debugger, where all macros are expanded and the include files are merged. Error Listing If the assembler detects any errors, it doesn't create an object file but an error listing file named ERR.TXT. This file is generated in the directory the source file was found (also please see document Appendix, section Environment and Environment Variable ERRORFILE). If the assembler was started from WinEdit or Codewright, it doesn’t produce that error file. Instead it writes the error messages in a special format in a file called EDOUT. Use WinEdit’s Next Error or Codewright’s Find Next Error command to see both the error position and the error message. © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 9 Implementation Features The HI-ASM assembler implements the "assembly language input standard for the M68HC05, M68HC11, M68HC16, and M68K families of microprocessors" of Motorola Inc. The assembler is fully compatible with the HI-ASM environment. Source Line Each source statement includes one or more of the following four fields: • label • operation • operand • comment Characters on the source line may be either upper or lower case. Directives and instructions are case insensitive, while symbols are case sensitive. Label Field The label field is the first field in the source line. A label is a symbol followed by a colon. Labels can include letters (A - Z or a - z), underscores (_), and numbers. The first character must not be a number. Labels are required on those assembler directives that define the value of a symbol (SET and EQU). For these directives, the label is assigned the value corresponding to the expression in the operand field. Labels within macros can be treated differently (please see section Macros). Operation Field The operation field follows the label field and is separated from it by white space. The operation field must not begin in the first column. An entry in the field is one of the following: • an instruction mnemonic • a directive name • a macro name Instruction mnemonics correspond to those defined in the CPU Reference Manual for the CPU 32 family: "Programmer’s Reference Manual” (M68000 PM/AD) of MOTOROLA. Operand Field The operand field, when present, follows the operation field and is separated from it by white space. When two or more operand subfields appear within a statement, they must be separated by a comma. © Copyright 1998 HIWARE HI-ASM 10 Macro Assembler Example BSET $0F, #$1F $0F and #$1F are subfields, and together they are the operand field. Comment Field The last field of a source statement is an optional comment field. A semicolon (;) is the first character in the comment field. An empty line is also a comment. The following examples show valid comment field formats: bra rts MyLabel: LOOP ; Comment follows an instruction ; Also a comment ; Also a comment Instruction Mnemonics The mnemonics allowed are defined in the CPU Reference Manual. "Programmer’s Reference Manual” (M68000 PM/AD) of MOTOROLA. Note: The macro assembler is not case sensitive regarding mnemonics. Supported Operators The following operators are supported: ________________________ + Unary plus – Two's complement ~ One's complement ! Unary not ________________________ * Multiplication / Division % Remainder after division ________________________ + Binary addition – Binary subtraction ________________________ << Shift left >> Shift right !< Shift left (Obsolete) !> Shift right (Obsolete) ________________________ © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 11 < Less than <= Less equal > Greater than >= Greater equal ________________________ = Equal == Equal != Not equal <> Not equal ________________________ & Bitwise logical AND !. Bitwise logical AND (Obsolete) ________________________ ^ Bitwise logical exclusive OR !x Bitwise logical exclusive OR (Obsolete) !X Bitwise logical exclusive OR (Obsolete) ________________________ | Bitwise logical ________________________ OR Operator precedence is consistent with the ANSI-C language. Operators with higher precedence are above operators of lower precedence in the table. Border lines delimit precedence boundaries. Operators of the same precedence are evaluated from left to right. Values are evaluated using 32-bit signed integer arithmetic. Defining Constants Numeric constants may be defined in either binary, octal, decimal or hexadecimal format. A decimal constant is a series of digits from the set 0 - 9. A binary constant is a leading % followed by a string of digits from the set 0 - 1. An octal constant is a leading @ followed by a string of digits from the set 0 - 7. A hex constant is a leading $ followed by a string of characters from the set 0 - 9, a - f, and A - F. A string constant is a series of printable characters enclosed with single or double quotes. Double quotes are only permitted within strings delimited by single quotes. Single quotes are only permitted within strings delimited by double quotes. Floating point constants are not supported. This can be summarized in the following syntax. NumericConstant © Copyright 1998 HIWARE = BinaryConst | OctalConst | DecConst | HexConst. HI-ASM 12 Macro Assembler BinaryConst OctalConst = = DecConst HexConst = = "%"("0"|"1"){"0"|"1"}. "@"("0"|"1"|"2"|"3"|"4"|"5"|"6"|"7") {"0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"}. DecDigit {DecDigit}. "$" HexDigit {HexDigit}. Old Style Support Old style constants are supported too, but shouldn't be used anymore. Old style constants have the following form: • Old style decimals are digits followed by the character 'D' or 'd'. • Old style binaries are zeros and ones followed by the character 'B' or 'b'. • Old style octals are digits followed by the character 'O' or 'o' or 'Q' or 'q'. • Old style hexadecimals are a leading digit followed by digits or characters 'A' 'F' or 'a' - 'f' followed by the character 'H' or 'h'. Reserved Names Register names, size specificators and operators cannot be used as label identifiers. Reserved symbols have the following names, which are case insensitive: D0..D7, A0..A7, ZD0..ZD7, ZA0..ZA7, ZPC, PC, CCR, SR, USP, SSP, AC0, AC1, USR, CAAR, CACR, DACR0, DACR1, DFC, DTT0, DTT1, IACR0, IACR1, ITT0, ITT1, MSP, ISP, SFC, TT0, TT1, VBR, AC, CAL, CRP, DRP, PCSR, PMMUSR, MMUSR, SCCR, SRP, TC, URP, VAL, FP0..FP7, FPCR, FCSR, FPIAR. Symbols Symbols are defined by the user to identify memory locations in program or data areas of the assembly module. Symbols can be defined as relocatable in the label field of an executable instruction or a data definition directive source line. A symbol defined in a source file can be made external using the XDEF directive. In another source file, it must be referenced by an XREF directive. Since its address is unknown to the referencing source file, it is considered to be relocatable. If a symbol is neither defined in the source file nor declared external using XREF, the assembler considers it to be undefined and generates an error. Expressions Expressions are composed of one or more symbols or constants, which are com- © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 13 bined with unary or binary operators. Valid symbols in expressions include: • The special symbol, an asterisk (*), represents the value of the location counter at the beginning of the instruction or directive, even when several arguments are specified. When a valid expression has been fully evaluated by the assembler, it may be categorized as one of three types of expressions: • Absolute expression: The expression has been reduced to an absolute value which is independent of the start address of any relocatable section. Thus, it is a constant. • Simple relocatable expression: The expression has evaluated to an absolute offset from the start of a single relocatable section. • Complex relocatable expression: The expression did not evaluate to an absolute offset from the start of a single relocatable section. Such expressions are not supported by the HI-ASM assembler. Translation Limitations and Implementation Restrictions Floating point constants and complex relocatable expressions are not supported. Lists of operands or symbols must be separated with commas. Includes may be nested up to 50 levels. The maximum line length is 1023 characters. The invocation depth for macros is not limited. The number of sections is not limited. Assembler Directives Some directives have two possible spellings. Such synonyms are only supported for compatibility reasons. They shouldn’t be used in new assembly files. ALIGN - Align Location Counter Syntax ALIGN <n> Description This directive forces the next instruction to a boundary that is a multiple of <n>, relative to the start of the section. The value of <n> must be a positive number. The ALIGN directive can force alignment to any size data structure. Values for <n> are in the range of 1 to 32767, though usually <n> will be 2 or 4. © Copyright 1998 HIWARE HI-ASM 14 Macro Assembler Example The following example aligns the HEX Label to a location which is a multiple of 16 (in this case, location 00010 (Hex)). 00000 RTS ALIGN 00010 HEX: JSR 16 Init Note: ALIGN can be used for code and data sections. However, if the smart linking option "–S" is used, this directive is ignored. (please see also LONGEVEN.) BASE - Set Number Base Syntax BASE <n> Description The directive sets the default number base for constants to <n>. The operand <n> may be prefixed to indicate its number base; otherwise, the operand is considered to be in the current default base. Valid values of <n> are 2, 8, 10, 16. Unless a default base is specified using the BASE directive, the default number base is decimal. Note: If the base value is set to 16, the number 1D is a decimal 1 in old style format, not a hexadecimal 1D. If a hexadecimal 1D is desired, $1D has to be written. CLIST - List Conditional Assembly Syntax CLIST [ON | OFF] Description The CLIST directive controls the listing of subsequent conditional assembly structures. It precedes the first directive of the conditional assembly structure to which it applies, and remains effective until a subsequent CLIST directive is read. When the ON keyword is entered with a CLIST directive, the listing file includes all directives and instructions in the conditional assembly structure. When the OFF keyword is entered, only the directives and instructions that are assembled are listed. The default is OFF. Example The following source code fragment... Bytes: © Copyright 1998 HIWARE CLIST EQU IFEQ JSR OFF 0 Bytes GetBytes HI-ASM Motorola 68K Assembler 15 ELSEC JSR ENDC GetWord ... produces this segment in the listing. Bytes: 00000 EQU 0 IFEQ Bytes FCALL GetBytes ELSEC DC - Define Constant Syntax [<label>:]DC[.<size>]<expression>{,<expression>} where <size> = B, W or L. Default is B. Description The DC directive defines constants in memory. It can have one or more <expression> operands, which are separated by commas. The <expression> can contain an actual value (binary, octal, decimal, hexadecimal, or ASCII). Alternatively, the <expression> is an expression that can be evaluated by the assembler. One memory block is allocated and initialized per expression. In code sections DC directives are handled like code. In data sections such a directive is like a DS which is initialized with the <expression>. The following rules apply to size specifications for DC directives: DC.B One byte is allocated for a numeric expression. One byte is allocated per ASCII character for strings. DC.W Two bytes are allocated for numeric expressions. DC.L Four bytes are allocated for numeric expressions. Example Label: © Copyright 1998 HIWARE DC.B "ABCD" DC.B 'A','B','C','D'; Equivalent to ; last statement DC.W %1001,@11,9,$9; Decimal 9. DC.B 1, 2, 3 ; 3 initialized ; bytes HI-ASM 16 Macro Assembler DCB - Define Constant Block Syntax [<label>:] DCB [.<size>] <count> ,<value> where <size> = B, W or L. Default is B. Description The DCB directive causes the assembler to allocate a memory block, initialized with the specified <value>. Values range from 1 to 4096. The block length is a multiple of <size> specified by the absolute expression <count>, which may not contain undefined, forward, or external references. Expressions are evaluated signed long. The value of each storage unit allocated is the sign-extended expression <value>, which may contain forward, or external references. In code sections DC directives are handled like code. In data sections such a directive is like a DS which is initialized with the <expression>. The following rules apply to size specifications for DCB directives: DCB.B One byte is allocated for numeric expressions. DCB.W Two bytes are allocated for numeric expressions. DCB.L Four bytes are allocated for numeric expressions. DS - Define Space Syntax [<label>:] DS [.<size>] <count> where <size> = B, W or L. Default is B. Synonym RMB is equal to DS.B Description The DS directive is used to reserve memory locations. The contents of the memory reserved are not initialized. The values allowed are in a range of 1 to 4096. The number of locations reserved is the multiple of <size> specified by <count>. The <count> expression must be absolute and cannot contain forward, undefined or external references. Space allocation is not in the same order as it is in the definition. That's why indexed addressing can only safely be used within one variable. Word and longword variables are automatically aligned on word bounda- © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 17 ries. Example Counter: Elements:DS.L DS.B DS.B 2 ;2 contiguous bytes in memory 3 ;3 contiguous bytes in memory ;can only be accessed by ;the Label Counter 5 ;5 contiguous longwords ;in memory The label references the lowest address of the defined storage area. ELSE - Conditional Assembly Syntax IF <condition> [<assembly language statements>] ... [ELSE] [<assembly language statements>] ENDIF Synonym ELSEC Description If <condition> is true, the statements between IF and ELSE are assembled, and if <condition> is false, the statements between ELSE and the corresponding ENDIF directive are assembled. Nesting of conditional blocks is allowed. ELSEC is a synonym for ELSE. Example See example under IFcc. END - End Assembly Syntax END Description The END directive indicates the end of the source code. Subsequent source statements in this file are ignored. The END directive in included files only skips subsequent source statements of this include file. Then assembly continues in the previous file in a regular way. © Copyright 1998 HIWARE HI-ASM 18 Macro Assembler ENDIF - End Conditional Assembly Syntax ENDIF Synonym ENDC Description The ENDIF directive indicates the end of a conditional block. Nesting of conditional blocks is allowed. Example See example of directive IFcc. ENDM - End Macro Definition Syntax ENDM Description The ENDM directive terminates a macro definition. EQU - Equate Symbol Value Syntax <label>: EQU <expression> Description The EQU directive assigns the value of the <expression> in the operand field to <label>. The <label> and <expression> fields are both required, and the <label> cannot be defined anywhere else in the program. The <expression> cannot include a symbol that is undefined or not yet defined, but it can contain a symbol defined in a XREF, or XREFB directive. The EQU directive does not allow forward references. Example MaxElement: MaxSize: Time: Hour: Minute: Second: © Copyright 1998 HIWARE EQU EQU DS.W EQU EQU EQU 20 MaxElement * 4 ; = 80 3 Time ; address of 1st word Time + 2 ; address of 2nd word Time + 4 ; address of 3rd word HI-ASM Motorola 68K Assembler 19 EVEN - Force Word Alignment Syntax EVEN Description This directive forces the next instruction to the next even address relative to the start of the section. EVEN is an abbreviation for ALIGN 2. Some processors require word and longword operations to begin at even address boundaries. In such cases, the use of the EVEN directive insures correct alignment. Note: EVEN can be used for code and data sections. However, if the smart linking option "–S" is used, this directive is ignored. (please see also ALIGN) FAIL - Generate Error Message Syntax FAIL <arg> | <string> Description The FAIL directive is ignored. It is only provided for compatibility reasons with older assemblers. IF - Conditional Assembly Syntax IF <condition> [<assembly language statements>] ... [ELSE] [<assembly language statements>] ENDIF Description If <condition> is true, the statements immediately following the IF directive are assembled. Assembly continues until the corresponding ELSE or ENDIF directive is reached, after which assembly moves to the statements following the ENDIF directive. Nesting of conditional blocks is allowed. <condition>:=<expression><relation><expression> <relation>:= "=" | "!=" | " >=" | ">" | "<="| "<" | "<>" The <expression> must be absolute and must be known at assembly time. © Copyright 1998 HIWARE HI-ASM 20 Macro Assembler IFcc - Conditional Assembly Syntax IFcc <condition> [<assembly language statements>] ... [ELSEC] [<assembly language statements>] ENDC Description These directives can be replaced by the IF directive. They shouldn't be used in new assembly files. Ifcc <condition> is true, the statements immediately following the IFcc directive are assembled. Assembly continues until the corresponding ELSE or ENDIF directive is reached, after which assembly moves to the statements following the ENDIF directive. Nesting of conditional blocks is allowed. The following table lists the available conditional types: ifcc <condition> Meaning ifeq ifne iflt ifle ifgt ifge ifc ifnc ifdef ifndef <expression> <expression> <expression> <expression> <expression> <expression> <string1>,<string2> <string1>,<string2> <label> <label> if <expression>== 0 if <expression>!= 0 if <expression>< 0 if <expression><= 0 if <expression> > 0 if <expression>>= 0 if <string1> == <string2> if <string1> != <string2> if <label> was defined if <label> was not defined Example The following is an example how to use conditional assembly directives: Bytes: EQU IFNE JSR 0 Bytes GetWord ELSEC JSR ENDC GetByte The value of Bytes determines the instruction to be assembled in the program. As shown, the JSR GetByte instruction is assembled. Changing the operand of the EQU directive to 1 causes the JSR GetWord instruction to be assembled instead. The following shows the listing provided by the assembler for these lines of code: © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler Bytes: 00000 21 EQU IFNE JSR 0 Bytes GetWord ELSEC JSR GetByte ENDC INCLUDE - Include Text from Another File Syntax INCLUDE <file specification> Description This directive causes the included file to be inserted into the source input stream. The <file specification> is not case sensitive, and may be enclosed in quotation marks. A pathname is required if the file to be included is not in the same directory as the original assembly source file; otherwise, the <file specification> is a filename. Example INCLUDE "D:\LIBRARY\macros.inc" LIST - Enable Listing Syntax LIST Description Write the listing information in the listing file. This option is selected by default. The source text following the LIST directive is listed until a NOLIST is read. LLEN - Set Line Length Syntax LLEN <n> Description Sets the number of characters from the source line that are included on the listing line to <n>. The maximum value of <n> is 132. LONGEVEN - Forcing Longword Alignment Syntax LONGEVEN Description This directive forces the next instruction to the next longword © Copyright 1998 HIWARE HI-ASM 22 Macro Assembler address (multiple of four) relative to the start of the section. LONGEVEN is an abbreviation for ALIGN 4. Note: LONGEVEN can be used for code and data sections. However, if the smart linking option "–S" is used, this directive is ignored. (please see also ALIGN) MACRO - Begin Macro Definition Syntax <label>: MACRO Description The <label> of the MACRO directive is the name by which the macro is called. This name must not be a processor machine instruction or assembler directive. For more information on macros, please see section Macros. MEXIT - Terminate Macro Expansion Syntax MEXIT Description Conditional assembly can be used within a macro. In that case, the expansion of the macro may terminate prior to termination of the macro definition. The MEXIT directive causes macro expansion to skip any remaining source lines ahead of the ENDM directive. The following is an example of the use of the MEXIT directive: Example call2: MACRO JSR JSR ifc mexit endc JSR endm \1 \2 '\3', ' ' ;is there a 3rd argument? \3 MLIST - List Macro Expansions Syntax MLIST [ON | OFF] Description When the ON keyword is entered with an MLIST directive, the © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 23 assembler includes the macro expansions in the listing file. When the OFF keyword is entered, the macro expansions are omitted from the listing file. This directive is not shown in the listing, and the default value is ON. NOLIST - Disable Listing Syntax NOLIST Synonym NOL Description Suppresses the printing of the assembly listing until a LIST directive is read. NOPAGE - Disable Paging Syntax NOPAGE Description Disables paginating in the listing. Program lines are continuously listed, without headings or top or bottom margins. ORG - Set Location Counter Syntax ORG <expression> Description The ORG directive sets the location counter to the value specified by <expression>. Subsequent statements are assigned memory locations starting with the new location counter value. The <expression> must be absolute and may not contain any forward, undefined, or external references. The ORG directive generates a section which is absolute. PAGE - Insert Page Break Syntax PAGE Description Advances listing to the top of the next page. © Copyright 1998 HIWARE HI-ASM 24 Macro Assembler PLEN - Set Page Length Syntax PLEN <n> Description Sets the listings page length to <n> lines. The maximum for <n> is 1024. If <n> is set to zero, no pages are generated. If the number of lines already listed on the current page is greater than or equal to <n>, listing will continue on the next page with the new page length setting. The default page length is 65 lines. SECTION - Declare Relocatable Section Syntax <name>: SECTION [<number>] Description This directive declares a relocatable section and initializes the location counter for the following code. The first SECTION directive for a section sets the location counter to zero. Subsequent SECTION directives for that section restore the location counter to the value that follows the address of the last code in the section. A section is a code section if there are only the directives DS, DC, and DCB. SET - Set Symbol Value Syntax <label>: SET <expression> Description Similar to the EQU directive, the SET directive assigns the value of the <expression> in the operand field to the symbol in the <label> field. The <expression> cannot include a symbol that is undefined or not yet defined. The value is temporary; it can be redefined by a subsequent SET directive. SPC - Insert Blank Lines Syntax SPC <count> Description Inserts <count> blank lines into the assembly listing. The values allowed for count are in a range of 1 to 65. This has the same effect as writing that number of blank lines in the assembly source. A blank line is defined by the assembler to be a line with only a carriage return. © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 25 TABS - Set Tab Length Syntax TABS <n> Description Sets the tab length to <n> spaces. The default tab length is 8. TITLE - Provide Listing Title Syntax TITLE "title" Synonym TTL "title" Description Print the <title> on the head of every page of the listing file. A title consists of a string of characters enclosed in quotes ("). XDEF - External Symbol Definition Syntax XDEF [.<size>] <label> [,<label>]... where <size> = B, W or L. Default is W. Synonyms GLOBAL, PUBLIC Description This directive specifies labels defined in the current module that are to be passed to the linker as labels that can be referenced by other modules linked to the current module. Example XDEF Global ;can be referenced in other modules XDEF AnyCase ; Note that the linker and ; assembler are case sensitive ; with names. XREF - External Symbol Reference Syntax XREF [.<size>] <symbol> [,<symbol>]... where <size> = B, W or L. Default is W. Synonyms EXTERNAL, XREFB © Copyright 1998 HIWARE HI-ASM 26 Macro Assembler Description This directive specifies symbols referenced in the current module but defined in other modules. The values (addresses) of these symbols are defined at linking time by the linker. Example XREF OtherGlobal; Reference "OtherGlobal" in ; another module. ; (See XDEF directive example.) Macros A macro is a template for a code sequence. Once a macro is defined, subsequent "calls" of the macro are replaced by its code sequence. Macro Overview A macro must be defined before it is called. When a macro is defined, it is given a name. This name becomes the mnemonic by which the macro is subsequently called. The assembler expands the macro definition each time the code calls the macro. The macro call causes source statements to be generated that can include macro arguments. A macro definition may contain any code or directive except nested macro definitions. Calling other previously defined macros is allowed, though. Source statements generated by a macro call are assembled just as though they had been placed at that point in the source file. To call a macro, write the macro name in the operation field of a source statement. Place the arguments in the operand field. The macro may contain conditional assembly directives that cause the assembler to produce in-line coding variations of the macro definition. A macro call produces in-line code to perform a predefined function. Every time the macro is called, code is inserted into the normal flow of the program so that the generated instructions are executed in-line with the rest of the program. Defining a Macro The definition of a macro consists of three parts: • The header statement, a MACRO directive with a label that names the macro. • The body of the macro, a sequential list of assembler statements, some possibly © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 27 including argument placeholders. • The ENDM directive, terminating the macro definition. See directives of section Assembler Directives for information about the MACRO, ENDM, MEXIT, and MLIST directives. The body of a macro is a sequence of assembler source statements. Macro parameters are defined by the appearance of parameter designators within these source statements. Valid macro definition statements include the set of processor assembly language instructions, assembler directives, and calls to previously defined macros. However, macro definitions may not be nested. Calling Macros Syntax [<label>:] <name>[.<sizearg>] [<argument>[,<argument>]...] Description Although a macro may be referenced by another macro prior to its definition in the source module, all macros must be defined before their first call. The name of the called macro must appear in the operation field of the source statement. Arguments are supplied in the operand field of the source statement, separated by commas. The macro call produces in-line code at the location of the call, according to the macro definition and the arguments specified in the macro call. The source statements of the expanded macro are then assembled under the same conditions and restrictions affecting any source statements. Nested macro calls are also expanded at this time. Macro Parameters As many as 36 different, substitutable parameters can be used in the source statements that constitute the body of a macro. These parameters are replaced by the corresponding arguments in a subsequent call to that macro. A parameter designator consists of a backslash character (\), followed by a digit (0 9) or an uppercase letter (A - Z). Parameter designator \0 corresponds to a size argument that follows the macro name, separated by a period (.). Consider the following macro definition: © Copyright 1998 HIWARE HI-ASM 28 Macro Assembler Example MyMacro: MACRO LOAD.\0 ENDM \1,\2 When this macro is used in a program, e.g.: MyMacro.B $12,D0 the assembler expands it to: LOAD.B $12,D0 Arguments in the operand field of the macro call refer to parameter designators \1 through \9 and \A through \Z, in that order. The argument list (operand field) of a macro call cannot be extended onto additional lines. At the time of a macro call, arguments from the macro call are substituted for parameter designators in the body of the macro as literal (string) substitutions. The string corresponding to a given argument is literally substituted wherever that parameter designator occurs in a source statement as the macro is expanded. Each statement generated in the execution is assembled in-line. It is possible to specify a null argument in a macro call by a comma with no character (not even a space) between the comma and the preceding macro name or comma that follows an argument. When a null argument itself is passed as an argument in a nested macro call, a null value is passed. All arguments have a default value of null at the time of a macro call. Labels Inside Macros To avoid the problem of multiply defined labels resulting from multiple calls to a macro that has labels in its source statements, the programmer can direct the assembler to generate unique labels on each call to a macro. Assembler–generated labels include a string of the form .nnnnn where nnnnn is a 5 digit value. The programmer requests an assembler–generated label by specifying \@ in a label field within a macro body. Each successive label definition that specifies a \@ directive generates a successive value of .nnnnn, thereby creating a unique label on each macro call. Note that \@ may be preceded or followed by additional characters for reasons of clarity and to prevent ambiguity. Macro Expansion When the assembler reads a statement in a source program calling a previously © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 29 defined macro, it processes the call as described in the following paragraphs. The symbol table is searched for the macro name. If it is not in the symbol table, an undefined symbol error message is issued. The rest of the line is scanned for arguments. Any argument in the macro call is saved as a literal or null value in one of the 35 possible parameter fields. When the number of arguments in the call is less than the number of parameters in the macro definition, no substitution is made. Starting with the line following the MACRO directive, each line of the macro body is saved and associated with the named macro. Each line is retrieved in turn, with parameter designators replaced by argument strings or assembler–generated label strings. Once the macro is expanded, source lines are evaluated and object code is produced. Nested Macros Macro expansion is done at invocation time, which is also the case for nested macros. If the macro definition contains a nested macro call of a previously defined macro, nested macro expansion takes place in-line. A macro can call itself, for recursion. A macro call is limited to the length of one line, i.e. 1024 characters. Defining Variables Variables can be defined with the DS directive and they must be in RAM. Separate sections should be used for data and code. This is the only way to ensure that only code is burned into any PROMs. The assembler makes no checks at all to prevent mixed code and data sections. Mixing C and Assembler Applications To build mixed C and assembler applications, you have to take the following aspects into consideration. Memory models, register usage, and calling conventions are of great importance. They do vary, depending on the processor used. Keep in mind the following points: • It is possible to mix modules compiled for different memory models in one appli- © Copyright 1998 HIWARE HI-ASM 30 Building Applications cation, but this must be done with caution (please see chapter Compiler, Back End). • Generally the HI-ASM compiler uses all the standard registers of the specific processor. • Only the calling conventions that are imposed by the specific compiler should be used, in order to ensure correct parameter passing. Note: For details please refer to the corresponding Compiler chapter of the HIASM manual for the processor you are using, and read the sections about Memory Models, Register Usage, and Call Protocol and Calling Conventions. References to External Symbols Symbols defined and exported (XDEF) in an assembly file can be referenced by a C file. There must exist an external definition in the C file for the symbol defined in an assembly file. Symbols defined and exported in a C file can be referenced by an assembly file using the directive (XREF). Of course no checks are made by the assembler or the C compiler. For this reason the user should be particularly careful. For example, it is possible to use a variable definition of the assembly file as a procedure in the C file, which would cause unpredictable program behavior. Building Applications An application consists of multiple files which are linked together. First, the different source files must be assembled or compiled. Then the object files are linked together and an absolute file is generated. The input for the linker is the linker parameter file, specifying all object files of the application as well as the location(s) for code and data. For visibility reasons during debugging, an assembly source file should only contain one code section and one data section, so you can see the appropriate variables for the actual PC. When you have multiple data sections you will see a huge list of variables, of which most variables are probably of no interest. © Copyright 1998 HIWARE HI-ASM Motorola 68K Assembler 31 Assembler Applications The entry points of the application must be mentioned in the linker parameter file using the commands INIT funcname or MAIN funcname (please see chapter Linker). Startup function In case the assembler application contains definitions of initialized variables in a RAM section (variables defined with the DC directive), a startup function must be linked with the application. This startup function will set the variables to their initialization value, according to the description which is generated by the linker. The function _Startup from the module startup.asm is an example of a startup function. The function _Startup performs the following actions: • Initialize the stack pointer with the value specified in the linker PRM file. • Initialize all the global variables in RAM sections with zero. • Set all the initialized variables in RAM sections to their initial values. • Jump to the function specified as main function (Directive MAIN in PRM file). Note: If some of the actions do not have to be performed, the corresponding code can be removed from the startup function. The application main function has to be defined by the command MAIN <mainfunc>. If this command is missing, the linker expects to find a function main as the application main function. When the linker finds a function called _Startup, this function is considered to be the startup function. If you wish to name your startup function differently, use the command INIT <startupfunc> (please see chapter Linker). Example INIT InitProc MAIN MainProc No Startup In case an application does not contain initialized variables, the startup function can be skipped. In that case the application entry point has to be defined with the following command INIT <entrypoint> Example © Copyright 1998 HIWARE HI-ASM 32 Building Applications INIT MyEntryPoint Note: Be careful, if you do not use a startup function, do not forget to initialize the stack pointer. For more details about linking refer to chapter Linker. Mixed C and Assembler Applications It is possible to link the generated object file with object files from the C compiler in the final application. Normally the application starts with the main procedure of a C file. All necessary object files - assembler or C - are assembled with the HI-ASM linker in the same fashion as pure C applications. Memory Maps and Segmentation Relocatable code sections are placed in the DEFAULT_ROM segment. Relocatable data sections are placed in the segment DEFAULT_RAM. There are no checks at all that variables are in RAM. If you mix code and data in a section you can't place the section into ROM. That's why we suggest separating code and data into different sections. The difference between a relocatable section and an absolute section (ORG) in an assembly file is only the place where you define the location of the section. For a relocatable section, it is specified in the linker parameter file and for an absolute section, it is specified in the assembly source file. In newly written source files, only relocatable sections should be used, because these are more flexible. If you want to place a relocatable section in a specific address range, you have to put the section name in the linker parameter file in the placement list. SECTIONS ROM 1 SpecialROM RAM = READ_ONLY 0x00200 TO 0x00FFF; = READ_ONLY 0x10000 TO 0x10FFF; = READ_WRITE 0x04000 TO 0x04FFF; PLACEMENT DEFAULT_ROM INTO ROM1; mySection INTO SpecialROM; DEFAULT_RAM INTO RAM; END © Copyright 1998 HIWARE HI-ASM Index Index Symbols .LST 6 .o 8 33 ENDIF 18 ENDM 18 Environment Variable 8 EQU 18 Errorfile 5 EVEN 19 Expressions 12 F A ALIGN 13, 22 ASMOPTIONS 7 Assembler Directive 13 FAIL 19 File Object 8 G GLOBAL 25 B BASE 14 Batch 6 H C I CLIST 14 Comment Field 10 Constants 11 H6 IF 19 IFcc 20 INCLUDE 21 Include Files 8 D DC 15 DC.B 15 DC.L 15 DC.W 15 DCB 16 DCB.B 16 DCB.L 16 DCB.W 16 Directive Assembler 13 DS 16 E ELSE 17 ELSEC 17 END 17 ENDC 18 © Copyright 1998 HIWARE L L6 Label Field 9 Lc 6 Ld 6 Le 6 Li 6 LIST 21 LLEN 21 LONGEVEN 21 M MACRO 22 Macro 26 Call 27 Definition 26 Expansion 28 HI-ASM 34 Labels 28 Overview 26 Parameter 27 Memory Model 6 MEXIT 22 Mixed C and Assembler 32 Mixing C and Assembler 29 MLIST 22 Model Memory 6 T TABS 25 TITLE 25 TTL 25 V V7 W N N7 Nested Macros 29 NOL 23 NOLIST 23 NOPAGE 23 O W7 W1 7 W2 7 WINEDIT.INI 6 X XDEF 25, 30 XREF 25 Object File 8 Operand Field 9 Operation Field 9 Operators 10 ORG 23 P PAGE 23 PLEN 24 PUBLIC 25 R Recursion in Macros 29 Register Names 12 Reserved Names 12 S S 22 SECTION 24 SET 24 SPC 24 Symbols 12 © Copyright 1998 HIWARE HI-ASM