.pn 95 .bp odd .mt 5 .mb 6 .pl 66 .ll 65 .po 10 .hm 2 .fm 2 .he .ft All Information Presented Here is Proprietary to Digital Research .tc 5 AS68 Assembler .ce 2 =================== ENTIRE SECTION MUST BE RE-WRITTEN =============== =================== STARTING WITH McCLURE'S STUFF =============== .sh Section 5 .qs .sp .sh AS68 Assembler .qs .sp 3 .he CP/M-8000 Programmer's Guide 5.1 Assembler Operation .tc 5.1 Assembler Operation .sh 5.1 Assembler Operation .qs .ix assembler (AS68) operation .pp 5 The CP/M-8000 Assembler, AS68, assembles an assembly language source program for execution on the a Z8000 microprocessor. It produces a relocatable object file and, optionally, a listing. The assembly language accepted by AS68 is identical to that of the Zilog Z8000 assembler described in the Zilog manuals: \c .ul MZ8000 Resident Structured Assembler Reference Manual M8000MASM(D4) \c .qu and the \c .ul 16-bit Microprocessor User's Manual, \c .qu third edition Z8000UM(AD3). Appendix D contains a summary of the instruction set. Exceptions and additions are described in Sections 5.6 and 5.7. .sp 2 .tc 5.2 Initializing AS68 .he CP/M-8000 Programmer's Guide 5.2 Initializing AS68 .sh 5.2 Initializing AS68 .pp If the file AS68SYM.DAT is not on your disk, you must create this file to initialize AS68 before you can use AS68 to assemble files. To initialize AS68, specify the AS68 command, the -I option, and the filename AS68INIT as shown below. .sp .ti 10 AS68 -I AS68INIT .sp AS68 creates the output file AS68SYMB.DAT, which AS68 requires when it assembles programs. After you create this file, you need not specify this command line again unless you reconfigure your system to have different TPA boundaries. .sp 2 .tc 5.3 Invoking the Assembler (AS68) .he CP/M-8000 Programmer's Guide 5.3 Invoking the Assembler (AS68) .sh 5.3 Invoking the Assembler (AS68) .qs .pp Invoke AS68 by entering a command of the following form: .sp 2 .in 8 .nf AS68 [-F d:] [-P] [-S d:] [-U] [-L] [-N] [-I] [-O object filename] source filename [>listing filename] .fi .in 0 .bp .ce .sh Table 5-1. Assembler Options .sp .in 5 .ll 60 .nf Option Meaning .fi .sp .in 14 .ti -9 -F d: .sp The -F option specifies the drive on which temporary files are created. The variable d: is the drive designation, which must be followed by a colon. If this option is not specified, the temporary files that AS68 creates are created on the current drive. .sp 2 .ti -9 -I .sp The -I option initializes the assembler. See Section 5.2 for details. .sp 2 .ti -9 -P .sp If specified, AS68 produces and prints a listing on the standard output device which, by default, is the console. You can redirect the listing, including error messages, to a file by using the >listing filename parameter. Note that error messages are produced whether or not the -P option is specified. No listing is produced, however, unless you specify the -P option. .sp 2 .ti -9 -S d: .sp The -S option indicates the drive on which the assembler initialization file, AS68SYMB.DAT, resides. This file is created when you initialize AS68. See Section 5.2. AS68 reads the file AS68SYMB.DAT before it assembles a source file. The variable, d:, is the drive designation; it must be followed by a colon. If you do not specify this option, AS68 assumes the initialization file is on the default drive. .sp 2 .ti -9 -U .sp Causes all undefined symbols in the assembly to be treated as global references. .in 0 .ll 65 .bp .ce .sh Table 5-1. (continued) .sp .in 5 .ll 60 .nf Option Meaning .fi .sp .in 14 .ti -9 -L .sp Ensures all address constants are generated as longwords. Use the -L option for programs that require more than 64K for execution or if the TPA is not contained in the first 64K bytes of memory. If -L is not specified, the program is assembled to run in the first 64K bytes of memory. If an address in the assembly does not fit within one word an error occurs. Appendix E describes all AS68 errors. .sp 2 .ti -9 -N .sp Disables optimization of branches on forward references. Normally, wherever possible, AS68 uses the 2-byte form of the conditional branch and the 4-byte BSR instruction to speed program execution and reduce the instruction size instead of the 6-byte JSR instruction. .sp 2 .ti -9 source filename .sp This is the only required parameter. It is the file specification of the assembly language source program to be assembled. .sp 2 .ti -9 >listing filename .sp If specified, the listing requested with the -P option is directed to the specified file rather than to your console terminal, the standard output device. The error messages are produced in the listing file. Note that if you do not request a listing file, you can still redirect the error messages to a file by specifying the greater than symbol (>) immediately followed by a file specification. .ll 65 .bp .in 0 .he CP/M Programmer's Guide 5.4 Assembly Language Directives .tc 5.4 Assembly Language Directives .sh 5.4 Assembly Language Directives .qs .ix assembly language directives .pp This section alphabetically lists and briefly describes the directives AS68 supports. .sp 2 .ce .sh Table 5-2. Assembly Language Directives .qs .sp .in 5 .ll 60 .nf Directive Meaning .fi .sp .in 17 .ti -12 comm label, expression .ix common directive (comm) .sp The common directive (comm) specifies the label and size of a common area, which can be shared by separately assembled programs. The linker, LO68, links all common areas with the same label to the same address. The size of the common area is determined by the value of the largest expression when more than one common area with the same label exists. .sp 2 .ti -12 data .sp .ix data directive The data directive instructs AS68 to change the assembler base segment to the data segment. .sp 2 .ti -12 bss .sp .ix bss directive The bss directive instructs AS68 to change the assembler base segment to the block storage segment (bss). Instructions and data cannot be assembled in the bss. However, symbols can be defined and storage can be reserved with the .ds directive in the bss. .sp 2 .ti -12 dc operand [,operand, ...] .sp .mb 5 .fm 1 .ix define constant directive (dc) The define constant directive (dc) defines one or more constants in memory. When you specify more than one operand, separate each with a comma. The operand can contain a symbol or an expression that is assigned a numeric value by AS68, or the value of the constant in decimal, hexadecimal, or ASCII notation. If you specify an ASCII value, you must enclose the string in single quotes ('). Although an ASCII character is only seven bits in length, each character is assigned a byte of memory. The eighth bit always equals zero. .in 0 .ll 65 .bp .ce .sh Table 5-2. (continued) .qs .sp .in 5 .ll 60 .nf Directive Meaning .fi .sp .in 17 .pp You can specify the constants to be bytes, words, or longwords. The list below illustrates the notation for each of these size specifications and describes the rules that apply to them. .mb 6 .fm 2 .sp 2 .in 23 .ti -6 dc.b The constants are byte constants. If you specify an odd number of bytes, AS68 fills the odd byte on the right with zeroes unless the next statement is another dc.b directive. When the next statement is a dc.b directive, the dc.b uses the odd byte. Byte constants are not relocatable. .sp .ti -6 dc.w The constants are word constants. If you specify an odd number of bytes, AS68 fills the last word on the right with zeroes to force an even byte count. The only way to specify an odd number of bytes is with an ASCII constant. Word constants can be relocated. .sp .ti -6 dc.l The constants are longword constants. If less than a multiple of four bytes is entered, AS68 fills the last longword on the right with zeroes to force a multiple of four bytes. Longword constants can be relocated. .sp 2 .in 17 .ti -12 ds operand .sp The define storage directive (ds) reserves memory locations. The contents of the memory that it reserves is not initialized. The operand specifies the number of bytes, words, or longwords that this directive reserves. The notation for these size specifications is shown below. .ix define storage directive (ds) .sp .nf ds.b reserves memory locations in bytes .sp ds reserves memory locations in words .sp ds.l reserves memory locations in longwords .fi .in 0 .ll 65 .bp .ce .sh Table 5-2. (continued) .qs .sp .in 5 .ll 60 .nf Directive Meaning .fi .sp .in 17 .ti -12 end .sp The end directive informs AS68 that no more source code follows this directive. Code, comments, or multiple carriage returns cannot follow this directive. .ix end directive .sp 2 .ti -12 endc .sp The endc directive denotes the end of the code that is conditionally assembled. It is used with other directives that conditionally assemble code. .ix endc directive .sp 2 .ti -12 equ expression .sp .ix equate directive (equ) The equate directive (equ) assigns the value of the expression in the operand field to the symbol in the label field that precedes the directive. The syntax for the equate directive is below. .sp label EQU expression .sp The label and operand fields are required. The label must be unique; it cannot be defined anywhere else in the program. The expression cannot include an undefined symbol or one that is defined following the expression. Forward references to symbols are not allowed for this directive. .sp 2 .ti -12 even .sp .ix even directive The even directive increments the location counter to force an even boundary. For example, if specified when the location counter is odd, the location counter is incremented by one so that the next instruction or data field begins on an even boundary in memory. .in 0 .ll 65 .bp .ce .sh Table 5-2. (continued) .qs .sp .in 5 .ll 60 .nf Directive Meaning .fi .sp .in 17 .nf .ti -12 globl label[,label...] .ti -12 xdef label[,label...] .ti -12 xref label[,label...] .fi .sp These directives make the label(s) external. If the labels are defined in the current assembly, this statement makes them available to other routines during a load by LO68. If the labels are not defined in the current assembly, they become undefined external references, which LO68 links to external values with the same label in other routines. If you specify the -U option, the assembler makes all undefined labels external. .sp 2 .nf .ti -12 ifeq expression .ti -12 ifne expression .ti -12 ifle expression .ti -12 iflt expression .ti -12 ifge expression .ti -12 ifgt expression .fi .sp .ix conditional directives All of the directives listed above are conditional directives in which the expression is tested against zero for the condition specified by the directive. If the expression is true, the code following is assembled; otherwise, the code is ignored until an end conditional directive (endc) is found. The directives and the conditions they test are listed below. .sp .nf ifeq equal to zero ifne not equal to zero ifle less than or equal to zero iflt less than zero ifge greater or equal to zero ifgt greater than zero .fi .sp 2 .ti -12 ifc 'string1', 'string2' .sp 0 .ti -12 ifnc 'string1', 'string2' .sp .ix conditional string directive The conditional string directive compares two strings. The 'c' condition is true if the strings are exactly the same. The 'nc' condition is true if they do not match. .in 0 .ll 65 .bp .ce .sh Table 5-2. (continued) .qs .sp .in 5 .ll 60 .nf Directive Meaning .fi .sp .in 17 .ti -12 offset expression .sp .ix offset directive The offset directive creates a dummy storage section by defining a table of offsets with the define storage directive (ds). The storage definitions are not passed to the linker. The offset table begins at the address specified in the expression. Symbols defined in the offset table are internally maintained. No instructions or code-generating directives, except the equate (equ) and register mask (reg) directives, can be used in the table. The offset directive is terminated by one of the following directives: .sp .nf bss data end section text .fi .sp 2 .ti -12 org expression .sp .ix absolute origin directive (org) The absolute origin directive (org) sets the location counter to the value of the expression. Subsequent statements are assigned absolute memory locations with the new value of the location counter. The expression cannot contain any forward, undefined, or external references. .sp 2 .ti -12 page .sp .ix page directive The page directive causes a page break which forces text to print on the top of the next page. It does not require an operand or a label and it does not generate machine code. .pp The page directive allows you to set the page length for a listing of code. If you use this directive and print the source code by specifying the -P option in the AS68 command line, pages break at predefined rather than random places. The page directive does not appear on the printed program listing. .in 0 .ll 65 .bp .ce .sh Table 5-2. (continued) .qs .sp .in 5 .ll 60 .nf Directive Meaning .fi .sp .in 17 .ti -12 reg reglist .sp .ix register mask directive The register mask directive builds a register mask that can be used by movem instruction. One or more registers can be listed in ascending order in the format: .sp R?[-R[/R?[-R?...]...]] .sp Replace the R in the above format with a register reference. Any of the following mnemonics are valid: .sp .nf A0-A7 D0-D7 R0-R15 .fi .sp The example below illustrates a sample register list. .sp A2-A4/A7/D1/D3-D5 .sp You can also use commas to separate registers as shown below. .sp A1,A2,D5,D7 .sp 2 .ti -12 section # .sp .ix section directive The section directive defines a base segment. The sections can be numbered from 0 to 15 inclusive. Section 14 always maps to data. Section 15 is bss. All other section numbers denote text sections. .sp 2 .ti -12 text .sp .ix text directive The text directive instructs AS68 to change the assembler base segment to the text segment. Each assembly of a program begins with the first word in the text segment. .bp .in 0 .fi .ll 65 .tc 5.5 Sample Commands Invoking AS68 .sh 5.5 Sample Commands Invoking AS68 .qs .he CP/M-8000 Programmer's Guide 5.5 Sample Commands Invoking AS68 .sp 2 .ti 8 A>\c .sh AS68 -U -L TEST.S .qs .ix invoking AS68 .ix AS68, invoking .sp .pp This command assembles the source file TEST.S and produces the object file TEST.O. Error messages appear on the screen. Any undefined symbols are treated as global. .sp 2 .ti 8 A>\c .sh AS68 -P SMPL.S >SMPL.L .qs .sp .pp This command assembles the source file SMPL.S and produces the object file SMPL.O. The program must run in the first 64K of memory; that is, no address can be larger than 16 bits. Error messages and the listing are directed to the file SMPL.L. .sp 2 .tc 5.6 Assembly Language Differences .sh 5.6 Assembly Language Differences .qs .he CP/M-8000 Programmer's Guide 5.6 Assembly Language Differences .pp .ix AS68 assembly language The syntax differences between the AS68 assembly language and Zilog's assembly language are listed below. .in 8 .sp .ti -3 1) All assembler directives are optionally preceded by a period (.). For example, .sp .nf .ti -1 .equ or equ .ti -1 .ds or ds .sp .ti -3 2) AS68 does not support the following Zilog directives: .sp .nf comline mask2 idnt opt .fi .sp .ti -3 3) The Zilog .set directive is implemented as the equate directive (equ). .sp .ti -3 4) AS68 accepts upper- and lower-case characters. You can specify instructions and directives in either case. However, labels and variables are case sensitive. For example, the label START and Start are not equivalent. .sp .ti -3 5) For AS68, all labels must terminate with a colon (:). For example, .sp .nf A: FOO: .fi .sp However, if a label begins in column one, it need not terminate with a colon (:). .sp .ti -3 6) For AS68, ASCII string constants can be enclosed in either single or double quotes. For example, .sp .nf 'ABCD' "ac14" .fi .sp .ti -3 7) For AS68, registers can be referenced with the following mnemonics: .sp .nf r0-r15 R0-R15 d0-d7 D0-D7 a0-a7 A0-A7 .fi .sp Upper- and lower-case references are equivalent. Registers R0-R7 are the same as D0-D7 and R8-R15 are the same as A0-A7. .ne 10 .sp .ti -3 8) For AS68, comment lines cannot begin with an asterisk that is immediately followed by an equals sign (*=), since the location counter can be manipulated with a statement of the form: .sp .nf *=expr .fi .sp .ti -3 9) Use caution when manipulating the location counter forward. An expression can move the counter forward only. The unused space is filled with zeros in the text or data segments. .sp .ti -4 10) For AS68, comment lines can begin with an asterisk followed by an equals sign (* =) but only if one or more spaces exist between the asterisk and the equals sign as shown below. .sp .nf * = This command loads R1 with zeros. .sp * = Branch to subroutine XYZ .fi .sp .ti -4 11) For AS68, the syntax for short form branches is bxx.b rather than bxx.s .sp .ti -4 12) The Zilog assembler supports a programming model in which a program consists of a maximum of 16 separately relocatable sections and an optional absolute section. AS68 distributed with CP/M-8000 does not support this model. Instead, AS68 supports a model in which a program contains three segments, text, data, and bss as described in Sections 2 and 3 of this guide. .in 0 .fi .ll 65 .bp .tc 5.7 Assembly Language Extensions .sh 5.7 Assembly Language Extensions .qs .he CP/M-8000 Programmer's Guide 5.7 Assembly Language Extensions .sp .ix assembly language extensions .pp The enhancements listed below have been added to AS68 to aid the assembly language programmer by making the assembly language more efficient: .sp 2 .in 8 .ti -3 1) When the instructions add, sub, cmp are used with an address register in the source or destination, they generate adda, suba, and cmpa. When the clr instruction is used with an address register (Ax), it generates sub Ax, Ax. .sp .ti -3 2) add, and, cmp, eor, or, sub are allowed with immediate first operands and actually generate addi, andi, cmpi, eori, ori, subi, instructions if the second operand is not register direct. .sp .ti -3 3) All branch instructions generate short relative branches where possible, including forward references. .ix branch instructions .sp .ti -3 4) Any shift instruction with no shift count specified assumes a shift count of one. For example, "asl rl" is equivalent to "asl #1,rl". .ix shift instruction .sp .ti -3 5) A jsr instruction is changed to a bsr instruction if the resulting bsr is shorter than the jsr instruction. .ix jsr instruction .ix bsr instruction .sp .ti -3 6) The .text directive causes the assembler to begin assembling instructions in the text segment. .ix .text directive .sp .ti -3 7) The .data directive causes the assembler to begin assembling initialized data in the data segment. .ix .data directive .sp .ti -3 8) The .bss directive instructs the assembler to begin defining storage in the bss. No instructions or constants can be place in the bss because it is for uninitialized data only. However, the .ds directives can be used to define storage locations, and the location counter (*) can be incremented. .ix .bass directive .sp .ti -3 9) The .globl directive in the form: .ix .globl directive .sp .ti -1 .globl label[,label] ... .sp makes the labels external. If they are otherwise defined (by assignment or appearance as a label) they act within the assembly exactly as if the .globl directive was not given. However, when linking this program with other programs, these symbols are available to other programs. Conversely, if the given symbols are not defined within the current assembly, the linker can combine the output of this assembly with that of others which define the symbols. .bp .ti -4 10) The common directive (comm) defines a common region, which can be accessed by programs that are assembled separately. The syntax for the common directive is below. .ix common directive (comm) .sp .ti -1 .comm label, expression .pp The expression specifies the number of bytes that is allocated in the common region. If several programs specify the same label for a common region, the size of the region is determined by the value of the largest expression. .pp The common directive assumes the label is an undefined external symbol in the current assembly. However, the linker, LO68, is special-cased, so all external symbols, which are not otherwise defined, and which have a nonzero value, are defined to be in the bss, and enough space is left after the symbol to hold expression bytes. All symbols which become defined in this way are located before all the explicitly defined bss locations. .sp .ix .even directive .ti -4 11) The .even directive causes the location counter (*), if positioned at an odd address, to be advanced by one byte so the next statement is assembled at an even address. .sp .ti -4 12) The instructions, move, add, and sub, specified with an immediate first operand and a data (D) register as the destination, generate Quick instructions, where possible. .in 0 .ll 65 .sp 2 .tc 5.8 Error Messages .sh 5.8 Error Messages .qs .he CP/M-8000 Programmer's Guide 5.8 AS68 Error Messages .pp Appendix E lists the error messages generated by AS68. .sp 2 .ce End of Section 5 .bp .he CP/M-8000 Programmer's Guide End of Section 5 .sp 50 .nx six