MOTOROLA FREEWARE 8-BIT CROSS ASSEMBLERS USER'S MANUAL EDITED BY KEVIN ANDERSON FIELD APPLICATIONS ENGINEER TABLE OF CONTENTS CHAPTER 1......................................................... 1 1.1 INTRODUCTION .......................................... 1 1.2 ASSEMBLY LANGUAGE ..................................... 1 1.3 OPERATING ENVIRONMENT ................................. 2 1.4 ASSEMBLER PROCESSING .................................. 2 CHAPTER 2 ........................................................ 3 2.1 INTRODUCTION .......................................... 3 2.2 SOURCE STATEMENT FORMAT ............................... 3 2.2.1 Label Field .................................... 3 2.2.2 Operation Field ................................ 4 2.2.3 Operand Field .................................. 4 2.2.3.1 M6800/6801 Operand Syntax ................ 5 2.2.3.2 M6800/M68HC04 Operand Syntax ............. 5 2.2.3.3 M6805/M68HC05 Operand Syntax ............. 5 2.2.3.4 M6809 Operand Syntax ..................... 5 2.2.3.5 M68HC11 Operand Syntax ................... 6 2.2.3.6 Expressions .............................. 6 2.2.3.7 Operators ................................ 7 2.2.3.8 Symbols .................................. 7 2.2.3.9 Constants ................................ 7 2.2.4 Comment Field .................................. 8 2.3 ASSEMBLER OUTPUT ...................................... 9 CHAPTER 3 - RUNNING THE ASSEMBLERS ............................... 10 3.1 ASSEMBLER INVOCATION .................................. 10 3.2 ERROR MESSAGES ........................................ 11 CHAPTER 4 - ASSEMBLER DIRECTIVES ................................. 12 4.1 INTRODUCTION .......................................... 12 4.2 BSZ - BLOCK STORAGE OF ZEROS .......................... 12 4.3 EQU - EQUATE SYMBOL TO A VALUE ........................ 13 4.4 FCB - FORM CONSTANT BYTE .............................. 13 4.5 FCC - FORM CONSTANT CHARACTER STRING .................. 13 4.6 FDB - FROM DOUBLE BYTE CONSTANT ....................... 13 4.7 FILL - FILL MEMORY .................................... 14 4.8 OPT - ASSEMBLER OUTPUT OPTIONS ........................ 14 4.9 ORG - SET PROGRAM COUNTER TO ORIGIN ................... 14 4.10 PAGE - TOP OF PAGE ................................... 15 4.11 RMB - RESERVE MEMORY BYTES ........................... 15 4.12 ZMB - ZERO MEMORY BYTES .............................. 15 APPENDIX A - CHARACTER SET ....................................... 16 APPENDIX B - ADDRESSING MODES .................................... 18 B.1 M6800/M6801 ADDRESSING MODES .......................... 18 B.2 M6804/68HC04 ADDRESSING MODES ......................... 19 B.3 M6805/68HC05 ADDRESSING MODES ......................... 21 i TABLE OF CONTENTS B.4 M6809 ADDRESSING MODES ................................ 22 B.5 M68HC11 ADDRESSING MODES .............................. 26 APPENDIX C - DIRECTIVE SUMMARY ................................... 28 APPENDIX D - ASSEMBLER LISTING FORMAT ............................ 29 APPENDIX E - S-RECORD INFORMATION ................................ 30 E.1 INTRODUCTION .......................................... 30 E.2 S-RECORD CONTENT ...................................... 30 E.3 S-RECORD TYPES ........................................ 30 E.4 S-RECORD EXAMPLE ...................................... 31 ii CHAPTER 1 GENERAL INFORMATION 1.1 INTRODUCTION This is the user's reference manual for the IBM-PC hosted Motorola Freeware 8 bit cross assemblers. It details the features and capabilities of the cross assemblers, assembler syntax and directives, options, and listings. It is intended as a detailed reference and an introduction for those unfamiliar with Motorola assembler syntax and format. Those experienced with Motorola assembler products may wish to examine the file ASEMBLER.DOC available with the cross assemblers, which briefly describes the differences between these assemblers and earlier, non-pc based versions. Assemblers are programs that process assembly language source program statements and translate them into executable machine language object files. A programmer writes his source program using any text editor or word processor that can produce an ASCII text output. With some word processors this is known as "non document" mode. Non document mode produces a file without the non-printable embedded control characters that are used in document formating. (Caution: assembling a file that has been formatted with embedded control characters may produce assembler errors. The solution is to convert the source file to ASCII text.) Once the source code is written, the source file is assembled by processing the file via the assembler. Cross assemblers (such as the Motorola Freeware Assemblers) allow source programs written and edited on one computer (the host) to generate executable code for another computer (the target). The executable object file can then be downloaded and run on the target system. In this case the host is an IBM-PC or compatible and the target system is based on a Motorola 8-bit microprocessor (6800, 6801, 6803, 6805, 68HC05, 6809, or 68HC11). The assemblers are the executable programs AS*.EXE where * is any of 0, 1, 4, 5, 9, or 11 depending on which microprocessor you are writing code for. The details of executing the assembler programs are found in Chapter 3. The assembly language format and syntax for the various processors is very similar with slight variations due to varied programming resources (instructions, addressing modes, and registers). These variations are explained in Appendix B. 1.2 ASSEMBLY LANGUAGE The symbolic language used to code source programs to be processed by the Assembler is called assembly language. The language is a collection of mnemonic symbols representing: operations (i.e., machine instruction mnemonics or directives to the assembler), symbolic names, operators, and special symbols. The assembly language provides mnemonic operation codes for all machine instructions in the instruction set. The instructions are defined and explained in the Programming Reference Manuals for the specific devices, available from Motorola. The assembly language also contains mnemonic directives Freeware Assemblers User's Manual which specify auxiliary actions to be performed by the Assembler. These directives are not always translated into machine language. 1.3 OPERATING ENVIRONMENT These assemblers will run on any IBM-PC, XT, AT, PS-2, or true compatible. The assemblers may be run off of a floppy disk drive or they may be copied onto a hard drive for execution. DOS 2.0 or later is required. 1.4 ASSEMBLER PROCESSING The Macro Assembler is a two-pass assembler. During the first pass, the source program is read to develop the symbol table. During the second pass, the object file is created (assembled) with reference to the table developed in pass one. It is during the second pass that the source program listing is also produced. Each source statement is processed completely before the next source statement is read. As each statement is processed, the Assembler examines the label, operation code, and operand fields. The operation code table is scanned for a match with a known opcode. During the processing of a standard operation code mnemonic, the standard machine code is inserted into the object file. If an Assembler directive is being processed, the proper action is taken. Any errors that are detected by the Assembler are displayed before the actual line containing the error is printed. If no source listing is being produced, error messages are still displayed to indicate that the assembly process did not proceed normally. 2 Freeware Assemblers User's Manual CHAPTER 2 CODING ASSEMBLY LANGUAGE PROGRAMS 2.1 INTRODUCTION Programs written in assembly language consist of a sequence of source statements. Each source statement consists of a sequence of ASCII characters ending with a carriage return. Appendix A contains a list of the supported character set. 2.2 SOURCE STATEMENT FORMAT Each source statement may include up to four fields: a label (or "*" for a comment line), an operation (instruction mneumonic or assembler directive), an operand, and a comment. 2.2.1 Label Field The label field occurs as the first field of a source statement. The label field can take one of the following forms: 1. An asterisk (*) as the first character in the label field indicates that the rest of the source statement is a comment. Comments are ignored by the Assembler, and are printed on the source listing only for the programmer's information. 2. A whitespace character (blank or tab) as the first character indicates that the label field is empty. The line has no label and is not a comment. 3. A symbol character as the first character indicates that the line has a label. Symbol characters are the upper or lower case letters a- z, digits 0-9, and the special characters, period (.), dollar sign ($), and underscore (_). Symbols consist of one to 15 characters, the first of which must be alphabetic or the special characters period (.) or underscore (_). All characters are significant and upper and lower case letters are distinct. A symbol may occur only once in the label field. If a symbol does occur more than once in a label field, then each reference to that symbol will be flagged with an error. With the exception of some directives, a label is assigned the value of the program counter of the first byte of the instruction or data being assembled. The value assigned to the label is absolute. Labels may optionally be ended with a colon (:). If the colon is used it is not part of the label but merely acts to set the label off from the rest of the source line. Thus the following code fragments are equivalent: here: deca bne here 3 Freeware Assemblers User's Manual here deca bne here A label may appear on a line by itself. The assembler interprets this as set the value of the label equal to the current value of the program counter. The symbol table has room for at least 2000 symbols of length 8 characters or less. Additional characters up to 15 are permissible at the expense of decreasing the maximum number of symbols possible in the table. 2.2.2 Operation Field The operation field occurs after the label field, and must be preceded by at least one whitespace character. The operation field must contain a legal opcode mneumonic or an assembler directive. Upper case characters in this field are converted to lower case before being checked as a legal mneumonic. Thus 'nop', 'NOP', and 'NoP' are recognized as the same mneumonic. Entries in the operation field may be one of two types: Opcode. These correspond directly to the machine instructions. The operation code includes any register name associated with the instruction. These register names must not be separated from the opcode with any whitespace characters. Thus 'clra' means clear accumulator A, but 'clr a' means clear memory location identified by the label 'a'. Directive. These are special operation codes known to the Assembler which control the assembly process rather than being translated into machine instructions. 2.2.3 Operand Field The operand field's interpretation is dependent on the contents of the operation field. The operand field, if required, must follow the operation field, and must be preceded by at least one whitespace character. The operand field may contain a symbol, an expression, or a combination of symbols and expressions separated by commas. The operand field of machine instructions is used to specify the addressing mode of the instruction, as well as the operand of the instruction. The following tables summarize the operand field formats for the various processor families. (NOTE: in these tables parenthesis "()" signify optional elements and angle brackets "<>" denote an expression is inserted. These syntax elements are present only for clarification of the format and are not inserted as part of the actual source program. All other characters are significant and must be used when required.) 4 Freeware Assemblers User's Manual 2.2.3.1 M6800/6801 Operand Syntax The format of the operand field for M6800/6801 instructions is: Operand Format M6800/M6801 Addressing Mode -------------- --------------------------- no operand accumulator and inherent direct, extended, or relative # immediate ,X indexed Details of the M6800/6801 addressing modes may be found in Appendix B. 2.2.3.2 M6804/68HC Operand Syntax For the M6804/68HC04, the following operand formats exist: Operand Format M6804/68HC04 Addressing Mode -------------- ---------------------------- no operand accumulator and inherent direct, extended, or relative # immediate bit set or clear , bit test and branch [ or ] register indirect ,# move indirect Details of the M6804/68HC04 addressing modes may be found in Appendix B. 2.2.3.3 M6805/M68HC05 Operand Syntax For the M6805/68HC05, the operand formats are: Operand Format M6805/68HC05 Addressing Mode -------------- ---------------------------- no operand accumulator and inherent direct, extended, or relative # immediate ,X indexed , bit set or clear ,, bit test and branch Details of the M6805/68HC05 addressing modes may be found in Appendix B. 2.2.3.4 M6809 Operand Syntax For the M6809, the following operand formats are used: 5 Freeware Assemblers User's Manual Operand Format M6809 Addressing Mode -------------- --------------------- no operand accumulator and inherent direct, extended, or relative # immediate ,X indexed < forced direct > forced extended ] extended indirect ,R indexed <,R forced 8-bit offset indexed >,R forced 16-bit offset indexed [,R] indexed indirect <[,R] forced 8-bit offset indexed indirect >[,R] forced 16-bit offset indexed indirect Q+ auto increment by 1 Q++ auto increment by 2 [Q++] auto increment indirect -Q auto decrement by --Q auto decrement by 2 [--Q] auto decrement indirect W1,[W2,...,Wn] immediate where R is one of the registers PCR, S, U, X, or Y, and Q is one of the registers S, U, X, or Y. Wi (i=1 to n) is one of the symbols A, B, CC, D, DP, PC, S, U, X, or Y. Details of the M6809 addressing modes may be found in Appendix B. 2.2.3.5 M68HC11 Operand Syntax For the M68HC11, the following operand formats exist: Operand Format M68HC11 Addressing Mode -------------- ----------------------- no operand accumulator and inherent direct, extended, or relative # immediate ,X indexed with X register ,Y indexed with Y register bit set or clear bit test and branch The bit manipulation instruction operands are separated by spaces in this case since the HC11 allows bit manipulation instructions on indexed addresses. Thus a ',X' or ',Y' may be added to the final two formats above to form the indexed effective address calculation. Details of the M68HC11 addressing modes may be found in Appendix B. The operand fields of assembler directives are described in Chapter 4. 2.2.3.6 Expressions. An expression is a combination of symbols, constants, algebraic operators, and parentheses. The expression is used to specify a value which is to be used as an operand. 6 Freeware Assemblers User's Manual Expressions may consist of symbols, constants, or the character '*' (denoting the current value of the program counter) joined together by one of the operators: + - * / % & | ^ . 2.2.3.7 Operators. The operators are the same as in c: + add - subtract * multiply / divide % remainder after division & bitwise and | bitwise or ^ bitwise exclusive or Expressions are evaluated left to right and there is no provision for parenthesized expressions. Arithmetic is carried out in signed two- complement integer precision (that's 16 bits on the IBM PC). 2.2.3.8 Symbols. Each symbol is associated with a 16-bit integer value which is used in place of the symbol during the expression evaluation. The asterisk (*) used in an expression as a symbol represents the current value of the location counter (the first byte of a multi-byte instruction). 2.2.3.9 Constants. Constants represent quantities of data that do not vary in value during the execution of a program. Constants may be presented to the assembler in one of five formats: decimal, hexadecimal, binary, or octal, or ASCII. The programmer indicates the number format to the assembler with the following prefixes: $ HEX % BINARY @ OCTAL ' ASCII Unprefixed constants are interpreted as decimal. The assembler converts all constants to binary machine code and are displayed in the assembly listing as hex. A decimal constant consists of a string of numeric digits. The value of a decimal constant must fall in the range 0-65535, inclusive. The following example shows both valid and invalid decimal constants: VALID INVALID REASON INVALID ----- ------- -------------- 12 123456 more than 5 digits 12345 12.3 invalid character A hexadecimal constant consists of a maximum of four characters from the set of digits (0-9) and the upper case alphabetic letters (A-F), and is preceded by a dollar sign ($). Hexadecimal constants must be 7 Freeware Assemblers User's Manual in the range $0000 to $FFFF. The following example shows both valid and invalid hexadecimal constants: VALID INVALID REASON INVALID ----- ------- -------------- $12 ABCD no preceding "$" $ABCD $G2A invalid character $001F $2F018 too many digits A binary constant consists of a maximum of 16 ones or zeros preceded by a percent sign (%). The following example shows both valid and invalid binary constants: VALID INVALID REASON INVALID ----- ------- -------------- %00101 1010101 missing percent %1 %10011000101010111 too many digits %10100 %210101 invalid digit An octal constant consists of a maximum of six numeric digits, excluding the digits 8 and 9, preceded by a commercial at-sign (@). Octal constants must be in the ranges @0 to @177777. The following example shows both valid and invalid octal constan ts: VALID INVALID REASON INVALID ----- ------- -------------- @17634 @2317234 too many digits @377 @277272 out of range @177600 @23914 invalid character A single ASCII character can be used as a constant in expressions. ASCII constants are preceded by a single quote ('). Any character, including the single quote, can be used as a character constant. The following example shows both valid and inval id character constants: VALID INVALID REASON INVALID ----- ------- -------------- '* 'VALID too long For the invalid case above the assembler will not indicate an error. Rather it will assemble the first character and ignore the remainder. 2.2.4 Comment Field The last field of an Assembler source statement is the comment field. This field is optional and is only printed on the source listing for documentation purposes. The comment field is separated from the operand field (or from the operation field if no operand is required) by at least one whitespace character. The comment field can contain any printable ASCII characters. 8 Freeware Assemblers User's Manual 2.3 ASSEMBLER OUTPUT The Assembler output includes an optional listing of the source program and an object file which is in the Motorola S Record format. Details of the S Record format may be found in Appendix E. The Assembler will normally suppress the printing of the source listing. This condition, as well as others, can be overridden via options supplied on the command line that invoked the Assembler. Each line of the listing contains a reference line number, the address and bytes assembled, and the original source input line. If an input line causes more than 6 bytes to be output (e.g. a long FCC directive), additional bytes (up to 64) are listed on succeeding lines with no address preceding them. The assembly listing may optionally contain a symbol table or a cross reference table of all symbols appearing in the program. These are always printed at the end of the assembly listing if either the symbol table or cross reference table options (Paragraph 4.8) are in effect. The symbol table contains the name of each symbol, along with its defined value. The cross reference table additionally contains the assembler-maintained source line number of every reference to every symbol. The format of the cross reference table is shown in Appendix D. 9 Freeware Assemblers User's Manual CHAPTER 3 RUNNING THE ASSEMBLERS 3.1 ASSEMBLER INVOCATION The Motorola Freeware Assembly programs are named as*.exe where '*' is any of 0, 1, 4, 5, 9, or 11 depending on which processor family you wish to assemble code for. For example, to generate M6800 code run the as0.exe program. To generate M68HC05 code run the as5.exe program, and so forth. To run the assembler enter the following command line: as* file1 (file2 . . . ) ( - option1 option2 . . . ) where file1, file2, etc are the names of the source files you wish to assemble. The source filenames may have extensions but the assembler does not check for any particular extension ( however, do not use the .S19 extension since that is the extension of the object file created by the assembler. Its creation would overwrite the source file when it is written to the disk). The options are one or more of the following: l enables output listing no disables output listing (default). cre enables the cross reference table generation s enables the symbol table generation c enables cycle counting noc disables cycle counting The minus sign preceding the option should be separated from the last file name by a space. These options may also be indicated to the assembler by the use of the OPT directive in the source file. The OPT directive is described in Paragraph 4.8. The object file created is written to disk and given the name 'FILENAME.S19' where 'FILENAME' is the name of the first source file specified on the command line. Any errors and the optional listing (if specified) are displayed on the screen. The listing and/or error messages may be saved to a file for later examination or printing by append an i/o redirection command to the command line. On the PC i/o redirection is indicated with the greater-than ('>') symbol followed by any new or existing file name. Command line examples: The command line as5 myfile would run the M6805/68HC05 assembler on the source file 'myfile'. The object file would be written to 'myfile.s19' and any errors would appear on the screen. 10 Freeware Assemblers User's Manual The command line as9 test.asm nexttest.s -l would run the M6809 assembler on the source files 'test.asm' and 'nexttest.s'. The object file would be written to 'test.s19' and any errors and the assembly listing would appear on the screen. The command line as9 test.asm nexttest.s -l cre s >test.lst would run the M6809 assembler on the source files 'test.asm' and 'nexttest.s'. The object file would be written to 'test.s19'. A listing would be created followed by a symbol table and cross reference which would all be written to the file test.lst . 3.2 ERROR MESSAGES Error diagnostic messages are placed in the listing file just before the line containing the error. The format of the error line is: Line_number: Description of error or Line_number: Warning ---- Description of error Errors in pass one cause cancellation of pass two. Warning do not cause cancellation of pass two but are indications of a possible problem. Error messages are meant to be self-explanatory. If more than one file is being assembled, the file name precedes the error: File_name,Line_number: Description of error Some errors are classed as fatal and cause an immediate termination of the assembly. Generally this happens when a temporary file cannot be created or is lost during assembly. 11 Freeware Assemblers User's Manual CHAPTER 4 ASSEMBLER DIRECTIVES 4.1 INTRODUCTION The Assembler directives are instructions to the Assembler, rather than instructions to be directly translated into object code. This chapter describes the directives that are recognized by the Freeware Assemblers. Detailed descriptions of each directive are arranged alphabetically. The notations used in this chapter are: ( ) Parentheses denote an optional element. XYZ The names of the directives are printed in capital letters. < > The element names are printed in lower case and contained in angle brackets. All elements outside of the angle brackets '<>' must be specified as-is. For example, the syntactical element (,) requires the comma to be specified if the optional element is selected. The following elements are used in the subsequent descriptions: A statement's comment field