Vector Graphic CP/M 2 ZSM Assembler User manual

cit/m 2
£ m 4 ;:miLt:=I
USERS MAN,UAL

ZStt ASSEMBLER FOR CP/M
Version 2.5
USER' S MANUAL
Revision A
February HJ, 1980
*
CP/M is a registerd trademark of Digital Research.

Copyright 1980 by Vector Graphic Inc.
All rights reserved.
Disclaimer
Vector Graphic makes no representations or warranties with respect to the
contents of this manual itself, whether or not the product it describes is
covered by a warranty or repair agreement. Further, Vector Graphic reserves
the right to revise this publication and to make changes from time to time in
the content hereof without obligation of Vector Graphic to notify any person of
such revision or changes, except when an agreement to the contrary exists.
Revisions
The date and reV1Slon of each page herein appears at the bottom of each page.
The revision letter such as A or B changes if the MANUAL has been improved but
the PRODUCT itself has not been significantly modified. The date and revision
on the Ti tie Page corresponds to that of the page most recently revised. When
the product itself is modified significantly, the product will get a new
revision number, as shown on the manual's title page, and the manual will
revert to revision A, as if it were treating a brand new product. EACH MANUAL
SHOULD ONLY BE USED WITH THE PRODUCT IDENTIFIED ON THE TITLE PAGE.

This manual is intended for ASSEMBLY
LANGUAGE programmers. It assumes a
moderate technical knowledge of small
computers, and familiari ty with the
basic operation of the Vector Graphic
system, the CP/M operating system, and
the z-sa instruction set.
This manual will describe the operation
of the ZSM Assembler for CP/M, including
all pseudo operations and syntax.
It assumes the user knows how to program
in assembly language using the sasa superset
form of Z-SO mnemonics. Vector Graphic can
supply a description of these mnemonics
in relation to the Zilog/Mostek mnemonics.

1.1
1.2
2.1
2.2
2.3
2.4
2.5
2.6
2.7
Calling ZSM from CCP •••••••.•.•••••.••••••••.••••••.••.•••••• 2 1
I..anguage eleInents.· ...•..•.•.•.••..•.........•..•......•....•. 2-2
Constants •••••••••••••••••••••••••••••••••••••••••••••••••••• 2 3
O~rators ••••••••••••••••••••••••••• '••••••••••••••••••••••••• 2-4
Registers , 2-5
Pseudo ops •••••••••••••.•••••••••••.•••••••••••••••••••••.••• 2 6
.Assembly errors •••••••••••••.•••.••.••.•.••••••.••••.•.•••••• 2 11

Z5Mfor cP/M is a program which converts z-sa assembly language text (source
code) into a sequence of machine language instructions (object code). The
latter can then be loaded into the corrputer's rnerooryand executed.
Z8Mis a "disk to disk" aSSembler, meaing that it takes a named source file
from a disk and puts the resultant object file back onto the disk. If
requested it can print or display on the console an "assembly listing" showing
both source and object code, or it can put the assembly listing on disk for
printing at a later time.
For users familiar with the M008version of Z5M,the CP/Mversion is similar
in most respects. The main difference is that you call it using a syntax
nearly the same as the cP/M 1.4 assembler, A5M.
Like the MO08Z8M, the CP/M version uses the sasa superset style of
mnemonics, as a convenience to programmers who began by learning sasa code.
Also, programs written for the SaS0 can be assembled using Z8M. Unlike the
MO08Z8M, the CP/M Z8Mdoes not have either the ENDor TABpseudo operations,
and it has several new pseudo operations, such as TITLE, RADIX,and MARGIN.
If you are not familiar with the S3S0 superset style of mnemonics, Vector
Graphic can supply a booklet which compares it instruction-by-instruction with
the Zilog/Mostek mnemonics. It is important to grasp how indexing is handled.
Under Zilog mnanonics, an operand might appear as (IX+d) where d is the offset
and IX is the index register. Under ZSM,it would be d(X)• Thus instead of
The same is true of IY, only it would appear as (Y) instead of (X). In
addition, an offset of zero may be omitted entirely. That is, (IX+0) need not
be written as a(X), it can simply be (X).
After 28Mhas assembled a source file, it puts the object file onto the
desired disk, giving it the file type .HEX. If you are familiar with CP/M, you
know that you first have to change the type of this file to .CC>1if you want to
be able to call it up as if it were a CCPcanmand, just by typing its name. To
do this, you type LOADXXXXX.HEX(return) after the CCPprompt A>, where XXXXX
is the name of the file. You can then type XXXXX(return) to execute the
program.

This section is included for users already familiar with Z8Mfor CP/M.
ZSM2.5 clears up the problems in version 2.2. Problems corrected are as
follows:
Print-file output
1. Pass 1 errors now print only once, not twice.
2. Tab characters in the source file are converted to spaces properly.
3. Errors that occur on a line that is also on the border of a page are now
handled correctly.
4. Pass 1 errors are now at the beginning of the print file.
5. The output format of pass 1 errors is now neatly aligned.
Error handling
1. Someerrors previously reported in pass 1 are now reported in pass 2.
2. There is improved detection of type "M" errors on lines that require a
label but have none.
3. TyPe~" errors are nowdetected for 16 bit values. Previously, only 8 bit
values were checked for overflow. This roodification affects "001", "DO",
and "DS
11
pseudo-ops.
4. No error now occurs when there is not a space or tab between an operand and
a following comment. That is, ";" is now a valid end-of-operand
character.
5. Type "M"errors no longer destroy the value of the last preceeding entry in
the Symbo1 Table. .
6. Overlappin; hex code, due to roore than one oro statement, is now detected
for up to 10 ORG's. More ORG's are unaffected, but also unchecked. A
message is produced if roore than leI oro's occurred, but it is not counted
as an error. The message serves only to remind the user that the
possibility of overlappin; code exists.
7. Errors concerning the MOVand MYIopcodes (Le. MOVM,2(X) or MOVM,M)are
nowdetected and reported.
1. The LINKpseudo-op nowallows nestin; up to seven levels instead of only
one.
2. Pass numbers are now reported on the screen to mark the assembler's
progress.
3. Durn; LINKin; , the nameof the file currently bein; LINKedis repe rted, in
order to mark proress through the first pass.
4. The total number of errors are now counted (in decimal) and displayed at
the end of the assembly.
5. There is a new pseudo-op: MARGIN.It provides a left-hand margin on PRN
files. It is documented in the body of the manual.

2.1 Calling ZSM from CCP (the CP M executive)
Make sure you have a CP/M 2 System Diskette in drive A, from which you have
done a wann or cold boot. Make sure your source file is on a diskette in one
of the drives. You invoke ZSM by typing, after the CCP prompt A>, one of the
following two forms:
ZSM <filename> (return)
ZSM <filename>.<3 parameters> (return)
In both cases, <filename> represents the name of an assembly·language source
file of the fonn <filename>.ASM. In other words, to assemble USERCUST.ASM,
simply reference the filename USERCUST. ZSM assumes you mean USERCUST.A.SM.
In the first case, the assembler looks for the source file on the drive
currently "logged in" under CP/M (usually drive A) and puts the object file
back onto the same drive. It also puts the assembler listing file onto that
drive, rather than printing it or displaying it on the console.
Whenever ZSM puts an object file onto a disk, the object file is always of
the form <filename>.HEX. The filename is the same name used when calling ZSM.
Whenever ZSM puts an assembler listing file onto disk, this file is always of
the form <filename>.PRN, again where the filename is the same name used when
calling ZSM. For example, if you assembler USERCUST.ASM, by typing ZSM
USERCUST (return), the result will be two new files on the same diskette:
USERCUST.HEX and USERCUST.PRN. If errors occur during assembly, they will be
listed in the PRN file as well as at the console.
The second command form is used to specify the origin of the source file,
the destination of the hex file, and the destination of the print file, if any
of these are different than the currently logged in drive. Each of the 3
parameters is a single letter, which have the following meaning:
The first - designates the disk drive which contains the source file.
Use A, a, C, or o.
The second - designates the drive which will receive the the hex file.
Use A, a, C, 0, or Z.
Z skips generation of the hex file altogether.
The third - designates the drive which will receive the print file.
Use A, a, C, 0, x, Y or Z.
X prints the listing immediately, rather than putting it
on a disk.
Y places the listing on the console, rather than a disk.
Z skips generation of the print file.

Thus, the command28MUSERCU8T• .ABC (return) indicates that the source file
U8ERCU8T.ASMis to be taken from disk A, that USERCU8T.HEXis to be put on
drive B, and that U8EROJ8T.PRNis to be put on drive C.
The command28MU8ERCUST.ABX(return) is the same except that it prints the
listing Unmediately rather than putting U8ERCUST.PRNon the disk.
The command2SMU8ERCUST.B2Y(return) takes U8EROJ8T.A8Mfrom drive B, does
not generate a hex file at all, and displays the assembly listing on the
console. This kind of commandmight be used for a quick assembly to check for
program syntax errors.
The command28MU8ERCU8T.AAA(return) is exactly the same as typing 28M
U8ERCUST(return).
2.2 Language elements
The source file has a general format as follows:
Note that line numbers are not required.
Each element, except for the comment, must be separated from the preceding
one by at least one space character or a tab character. Tab characters cause
the elements to print on columns \vhich are even multiples of 8 from the left
edge.
The LABELis optional. If present, it will be entered into the symbol
table. Whether or not it is present, its position must be followed by a space
or colon. That is,
is not, because it is not preceded a space. Labels may include any of the
following characters:
ABCDEFGHIJKLMNOPQRSTUVWXY 2
a b c d e f g h i j k 1 m n 0 p q r s t u v w x y z
~ 1 234 5 6 7 8 9@ • ( ] { } \ I ' - ~
To avoid ambiguity, however, the first character may not be • or 0-9. In
addition, a label may be of any length up to 47 characters. All characters are
significant. In normal use, though, up to 12 characters should suffice; and
over 14 characters will look a little strange on the listing.
The OPCODErust either be a 2-80 opcode or a pseudo-ope Both are explained
later.

The OPERANDS vary. There can be any number of them, depending on whether
they are operands for an opcode or a pseudo-op. There are also instances where
there are no operands, and therefore this field can, in some cases, be omitted.
If more operands are supplied that are needed, the extras are ignored.
The COMMENT field is totally ignored by the assembler, except for printing
it on the listing. Comments are used only for documentation or clarity, and
can be omitted altogether. If present, comments should be preceeded by a
semicolon (;). The semicolon will cause a TAB to the third TAB setting,
whereas its absence will result in the comment appearing immediately to the
right of the operand field.
There is one exception to the above format, and that is the case of an
all-comment line. If the first character of the line (after the line number
and space) is either an asterisk (*) or semicolon, the entire line will be
treated as a comment.
ASCII constants are indicated by enclosing the appropriate character in
single quotes (.). Any ASCII character can appear between the quotes, except
for (1) control Characters, having an ASCII code of under 20 hex; (2) the
single quote character, ASCII code 27 hex; and (3) the DEL character, 7F hex.
Numeric constants may be in any of four bases - 2, 8, 10, and 16. A
specific base is indicated as follows:
t*itHindicates hexadecimal (base 16) - for example 1C7H
***Q indicates octal (base 8) - for example 62Q
***B indicates binary (base 2) - for example l0l0lB
***0 or just *tt indicates decimal (base 10) - for example 1930 or 193
Regardless of base, all numeric constants must begin with a digit, 0-9.
(This is to prevent ambiguity with labels.) Thus A07 hex would have to be
written as 0A07H.
There is one special numeric constant, denoted by the symbol $. This
constant is always equal to the address of the current line; that is, the
memory location that the current line will be written into when it is loaded.
Note that this reflects the address of the beginni1'l3of the current line, not
the next line (as in some assemblers). As an example, consider that

2.4 Operators
ZSM recognizes 10 operators. ' heyare as follows:
+ addition
subtraction, or negative (as in -1)
* multiplication
/ division
% modulo (remainder of division)
& logical AND
logical OR
i logical EXCLUSIVE-oR
> rotate right (1101018>3 yields 1011108)
< rotate left (11101108<1 yields 11011018)
All arithmetic operators treat their operands as unsigned 16-bit quantities,
and answers are truncated to 16 bits. All logical operators perform their
function on a bit-by-bit basis, and they also treat their operands as 16-bit
values.
Operators combine with constants to form expressions. In an expression, all
operators are evaluated in a strict left-to-right order, with no precedence of
operators.
Thus consider the following situation:
TEST has been assigned the value 1000H.
INC has been ass igned the value 6.
The expression encountered is TEST*6+INC17<8.
The procedure would be TEST*6 (6000H) +INC (6006H) 17 (6007H) <8 (0760H). Thus
the resulting value is 760H.

2.5 Registers
The Z-80 has a number of registers, all of which have a specific symbolic
reference. ZSMsupports these references, as follows.
register B - B
register C - C
register D - D
register E - E
register H - H
register L - L
accumulator - A
memory - M
A & flags - PSW
Stack Ptr - SP
Index reg X - IX
Index reg Y - IY
Also may be called DE for register-pair instructions
Also maybe called HL for register-pair instructions
Although not supported by ZSM,also called (HL)
Program Status ~rd, may also be called AF
Also may be called X for brevity
Also may be called Y for brevi ty
Of course, the Z-80 also has registers A', B', C', D', E', H', L', F', PC,
I, and R, but these are never explicitly referred to in an instruction, so no
special designation is needed.

2.6 Pseudo-ops
ZSMsupports a large number of pseudo-ops. They will be explained now.
The ORGpseudo-op specifies where the object code is to be put. Assembled code
and data is assembled starting at the address specified as the operand to the
ORGpsuedo-op, and proceeds upward, until the end of the program or another
OR:i.A program can contain as manyOR:isas desired. Since ORGis handled in
pass 1, any symbol appearing in the operand nust already be defined.
The LINKpseudo-op allows separate program files on the disk to be 'linked
together' and assembled as one file. The LINKoperand is a source file name,
enclosed in single quotes.
Linking to a file is like a subroutine; that is, when the linked-to file is
exhausted, assembly of the original program will continue from where it was
left off at. For example,
XXX:
XXX:
XXX:
LXI
LINK
WJV
H,413013H
'TEST'
A,M
will cause the entirety of the file TESTto be assembled between the LXI and
the MOV. One note, though: files that are linked to must not contain an END
pseudo-ope Up to seven levels of LINKfiles may be nested.
The EQUpseudo-op simply equates the label associated with it to the value of
the operands.
TEN: EQU 10
'lWEN'IY:EQU 2*10
The above code would cause the label TENto have the value 113, and TWENTYto
have the value 20.

REO Request value
The REQpseudo-op is similar to the EQUpseudo-op, only instead of an explicit
value being specified, the system console is prompted for the value. The
pranpt is specified as the operand. For example,
TEST: REQ'Input:'
Input:
to be displayed on the console during pass 1 of the assembly. The operator must
then type the value to be associated with the label. For example, if the
operator had typed '56H' in response to the prompt, then TESTwould have a
value of 56 hex.
' he PRTpseudo-op allows infonnation to be displayed on the console during pass
2. If operands are present, they are displayed, otherwise, just a carriage
return/linefeed is printed. For example,
TEST: EQU
PRT
7000H
'' his is a test ',TEST
The NLIST pseudo-op will cause code following it not to be listed. Note that
this overrides any options which mayhave been specified in the commandstring;
If the E option was used, nothing will be listed (errors or not) after a
NLIST.
' he LIST pseudo-op cancels the effect of the NLISTpseudo-op. If there has been
no NLIST, then this has no effect.

IFF If false - conditional assembly
The block of code following the IFF pseudo-op will be assembled only if the
operand evaluates to 0.
1FT If true - conditional assembly
The block of code following the 1FT pseudo-op will be assembled only if the
operand evaluates to anything other than 0.
The DBpseudo-op assigns its operands to successive melOOrylocations. Either
numeric or ASCII operands may be present, but either one must evaluate to only
8 bi ts. This means that only one ASCII character may be included per operand.
For example,
'z' is a special case of the [B pseudo-op, and it is equivalent to DB0. For
example,
XXX: Z and
XXX: DB0
are equivalent.
The OW pseudo-op is basically similar to DB, only it defines two bytes at a
time, rather than 1. Also, the two bytes are in Intel standard low/high
format.
The DDpseudo-op is exactly like OW, only the two bytes are put in high/low
format.

The DT pseudo-op allows ASCII text to be put into memory. The desired text
IIlJst be enclosed by single quotes. For example,
TEST: DT' ABCDEF'
DTH Define text tenninated high
The DTHpseudo-op is like DT, only the last character is ORedwith 80Hbefore
it is written out. In the above example, the last byte ~uld be C6 hex.
The DTZpseudo-op is like DTalso, only it causes a byte of ~~ to be appended
to the text string. Thus the example ~uld be 41 42 43 44 45 46 13~.
The DS pseudo-op causes the assembler to skip over the number of bytes
specified by the operand. Since the object file is scatter loaded, the area
skipped over will remain undisturbed.
The FILL pseudo-op is similar to OS, only it fills the area with a constant,
rather that skipping over it. The constant to fill with is specified with the
second operand. For excmple,

Type TITLE <title>, with no quotation marks around <title>. For example,
TITLE 'Ibis is a program
will cause "This is a program" to print at the top of every page in the
assembly listing.
This pseudo op sets the radix for all numbers used in the source program which
do not have a specific number base designation such as H or D attached. It can
appear anywhere in the text, and will apply to all numbers in the text because
it is read by the assembler in the first pass. Only use it once within the
text. If you do not use the RADIX pseudo op, ZSM defaults to a radix of 10.
For example, to specify that all numbers without another number base
designation are hexadecimal, set the radix to 16. To use binary, set the radix
to 2.
MARGIN 'Ibiscreates a left-hand margin in printed output (PRN files).
The MARGIN pseudo-op requires a parameter in absolute or symbolic fom that
evaluates to a value fran 13 to 131. 'Ibisnumber designates the column where
printing should start.