Download HI-ASM 68K Assembler

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