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 nowneatly 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 now detected for 16 bit values. Previously, only 8 bit
values were checked for overflow. This roodification affects

"001",

"DO",

and "DS11pseudo-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 now allows 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 nowcounted (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 CP1Mexecutive)
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

abcde

f

g

h

i

j

k 1

m n

0

p q

r stu vwxyz

~ 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 may be 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 many OR:isas desired. Since ORGis handled in
pass 1, any symbol appearing in the operand nust already be defined.

The LINK pseudo-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 maybe 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 80H before

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 readbythe 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 fran13to 131. 'Ibisnumber designates the column where
printing should start.

There are ten assembly errors. Note that an error doesn't necessarily cause
the program to assemble wrong, particularly if the error is a syntax error in

something like a TABstatement. Nevertheless, all errors should be avoided.

The errors are as follows.

A Argumenterror - This is caused by an invalid character in an operand

field, or an ASCIIconstant which is out of range.

o

Duplicate label error - This indicates that a symbolic namewas used more

than once as a label. The first value will be used.

J Jumperror - This indicates a relative jump (JR, JRZ, JRNZ, JRC, JRNC,

DJNZ)to a label which is out of range. The relative jumpshould be replaced

with an absolute one. There is one small ambiguity with this error: If you
have a relative jumpto a non-existant label, you will get a J error instead of

a U error. Although perhaps the U would be more appropriate, the way the

errors are handled gives J priority.

r. r.abel error

characters.
M Missing label error - This indicates that an EQUor REQpseudo-op was

encountered, but there was no label on the line. Obviously, a label is
necessary for either of these.

o

Opcodeerror - This is caused

by

an illegal or missing opcode. Actually,

misspelling is the most cammoncause of this error, or starting the opcode in

the first columninstead of the second.

R Register error - This indicates that an illegal value was found where a

register was eXPeCted.

S Syntax error - This is caused by missing operands or improper use of
operators.

U Undefinedsymbolerror - This indicates that a symbolwas used, but that
the symbolhas not been defined.

V Value error - This indicates that the value computedis out of range for

the operation being used, specifically a t~byte instruction, or a r:s.

AP'ENCIX A

ASCU

coce CHART

,• .ASCII: Amwican Standard' CQd. for IntorrnaUQft

IntlrChlng&

Standard

No.

X3.4-1968 of tne Ame,;CItI

Naticnai Standardllnfti1utao

II,.

'\ 0 "0:

,0.

10

1

I

1"

I

1

I

1

I

,

Bits

II,

'I

0

I

0

1 I 1

o

!

0

:

1

I

1

I

I

Its

,~ 0 1

o

I

1

!

01

1

I

01

1

t"i3~~,

•••

0

I

1

I

2

;

3

I

4

I

5

6

7

+.ew+

!

i

I

i

t

,

0000

0

NULi DLE:

I

SP

I

0

i

@)

I

P

I

,

.

•

!

t

i

J

000.1

1

SOH! Del

1

,

1

I

A

I

Q

j'-

CI

~. CI

0010

2~

STX I CC2.!

.1

2.

B

R.

,

I»

I

i

"

r

t

,

.

--

00

l'

1

3

ETX;Da'

#

3

,

c:

I

S',

I

i

,

e

$

,

.

o

1:O~O

4

EOT· DC4~

$

4·

D:

I

T

cI, '

t

I

I

0, l' a 1

S

ENQ.

NAKl

%.

5

E

U.

I

•

II

I

o. r

lO

6,

ACK

SYN

&"

6.

F

V

I

f

y

0:

t

l' 1

T

BEL.

ETB:

i

I

T

G·

w·

I

.'

t

•

I

I

---

t

000.

a

BS

,CANI

("

a

H·

x

I

h

x

lOa

1"

9

HT;

EM

)

9

I

y'

r

I

y

1:

0

l' 0:

A.

LF

StJ8~

*

•

J:

Z

1

z:

..

10:1"-1"·

B

VT'ESC:

+-

.'

K.

t:

Ie

I

{

I

I'

T0'0

C

FF

FS

<

L

I

\

I

I

I

I

I

I

I

-

1".10 1

D.

CR·

GS

i

-

•

M

]

•

I

}

I

I

t.

l

1'0

E

so :

IS

I

>-

I

N

-

••

i

""""

••

:

.,

I

I

1

t

t

1:

F

I

us

I

/

"

I

o·

I

.'IDEL.

51,

!-

..

'

•

AU cnancmn

i"

me. two columns ana SP

ISgac:.)

are

no~nung.