Digital-Research-Source-Code/CPM OPERATING SYSTEMS/CPM 8000 (CPM8K)/P-CP M-Z8K SOURCES/pg/pgm5.dri

.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