PASM Feb1980 pdf

Manual

PASM

Lifeboat Associates

:

'

1651

Third Avenue

;é

New York,

_NY.

10028

á'

Tel:

₍₂₁₂₎

860-0300

"'

"'7

TWX: 710-581-2524 (LBSOFT NYK)

.

*

'-

Telex: 640693 (LBSOFT NYK)

PHOENIX SOFTWARE LTD. PASM

User"s Manual

Revision

1.0 February

I,

1980

Written

by

Neil

_J.

Colvin

Copyright

1980 by Phoenix Software

Associates Ltd.

Reproduced

with

Permission arid

Distributed

by

LIFEBOAT ASSOCIATES

1651

Third

Avenue

New _York, N. Y. ₁₀₀₂₈

Tel:

(212) 860-0300

TWX: _710-581-2524

PSA Macro

Chapter

t:

Irítroductioa

Chapter 1

Introduction

PASM

is

the Pheoníx _{Software Associates Ltd.} symbolic assembly program for microprocessors which execute the Z80 (a _{trademark of}

Zilog, Inc.) instruction set.

It

is a two-pass assembler (requiring the source program _to be read _{twice to complete the} assembly _process)

designed to run under _the Phoenix _{Software Associates Ltd.} PDOS _(or

similar) operating system.

It

is

therefore device independent, allowing _{complete user}

flexibility

in the selection of standard input

and _{output device options.}

The _{assembler performs} many functions, making machine language programming _{easier, faster,} and _more

efficient.

_{Basically, the}

assembler processes the Z80 programmer"s _{source program statements} by

translating mnemonic _operation codes _{to the binary} codes needed _in machine _{instructions,}

relating

symbols _{to numeric values, assigning}

relocatable _{or absolute} memory addresses

for

program instructions and

data, and _{preparing an output}

listing

_{of the program which includes} any _errors encountered during the assembly.

The PSA Macro Assembler _{also contains a powerful macro capability}

which allows the programmer to create new language elements, thus

expanding and _{adapting the assembler to perform specialized functions}

tor each programming _job.

In addition, the PSA Assembler _{provides the}

facilities

_required

to specify program module _{linkages, allowing the} PSA _{Linkage Editor} (LINK) _to

link

_{independently} assembled _program modules _{together into} a single executable _program. This allows

for

the modular and

systematic development _{of large prograins,} and

for

_{easy sharing of} common program modules among

different

_programs.

Statements

Assembler _{programs are usually prepared on a terminal, with the}

aid of a _text editing _program. A program consists of a sequence of

statements in the assembly _language. Each _{statement is normally}

written

on one

line,

and _terminated by _{a carriage}

return/line

_feed sequence. PSA Macro Assembler _{statements are free-format. This} means that the various statement elements _are not placed at a

specific numbered column _{on the}

line.

There _{are four elements in an assembler statement (three of which}

are optional), separated from each other by _{specific characters.} These _{elements are}

identified

by

their

_{order of appearance in the}

statement, and by _{the separating (or delimiting) character which}

follows _or precedes _{the elements.}

PSA Macro Assembler

Chapter

I:

Introduction

Instruction Formats

The Z80 _{uses a variable length}

instruction

_format. A _given machine _{instruction may} be _{one, two, three, or four bytes long} depending _{on the specific} machine code and _{on the addressing} mode

specified. The PSA Assembler _{automatically produces the correct} number _of machine code _bytes

for

_the

particular

_{operation specified.}

Appendix A _{specifies the various} machine code mnemonics _accepted by

the assembler and _{the format of the} operands _required.

Statement Format

As _{previously described, assembler statements consist of a}

combination of a label, an _operator, one _or more operands, and a

cownent; the

particular

combination depends _{on the statement usage} and _{operator requirements.}

The _{assembler interprets} and _{processes these statements,}

generating one _or more binary instructions _or data bytes, _or performing sorne assembly control _process. A _statement must _contain

at least one of these elements, and rnay contain

all

four. Sorne

statements have _{no operands, while others may} have _many.

Statement labels, operators, and operands _may be _represented

numerically _{or symbolically.} The _{assembler interprets}

all

symbols and _replaces them _{with a numeric (binary) value.}

Symbols

The _{progranuner uiay create} symbols _{to use as statement labels, as}

operators, and _{as operands.} A symbol _{may consist of any combination}

of from one _{to six characters} from the following _set: The 26

letters:

A-Z

Ten

digits:

O-9

Three _{special characters:}

$ _{(Dollar Sign)} % _(Percent)

. (Period)

These _{characters constitute the} Radix-40 character set (so named because

it

contains only 40 _characters). Any _{statement character}

which is not in the Radix-40 set is treated as a symbol delimiter when _encountered by _{the assembler.}

The

first

_{character of a symbol} must _not be _numeric. Symbols _may

also not contain embedded _spaces. A symbol may contain more than six characters, but only the

first

six are used by _{the assembler.}

PSA Macro

Chapter

l:

Introduction

Labels

A _{label is the symbolic} name created by the programmer to

identify

a statement.

If

present, the label is written as the

first

i.tem _in a statement, and _{is terminated} by _{a colon (:}

).

A _statement may contain more than one label,

in

which case

all identify

the same

statement. Each _label must be _followed by _{a colon,} however. A

statement may consist of

just

a label (or labels), in which case the

label(s)

identifies

the following statement.

When _{a symbol is} used _{as a label,}

it

specifies a symbolic

address. Such symbols _{are said to} be _defined (have _{a value).} A

defined symbol _{can reference} an instruction _{or data byte at} any point

in

the program.

A label can be defined with only one value.

If

an _{attempt is} made _{to redefine} a label with a

different

value, the second value is

ignored, and _{an error is indicated.} The _{following are legal labels:} $SUM:

ABC:

Bl23:

WHERE%:

The _{following are}

illegal:

30QRT:

(First

_character must _not be _a

digit)

AB CD: (Cannot _contain embedded space)

If

too many characters are used _in a label, only the

first

six

are used. For example _{the label} ZYXWVUTSR:

is

_recognized by _the

assembler to be _{the same as} ZYXWVUABC:

.

Operators

An _{operator may be} one of the mnemonic machine instruction codes, a pseudo-operation code which directs the assembly _{process, or} a _user

defined code _(either pseudo-op _{or macro).} The _assembler pseudo-op codes _{are described in Chapter} 3 _{and summarized in Appendix B.}

The _operator element _{of a statement}

is

_terminated by _any

character not in the Radix-40 set (usually a space _or a tab).

If

a

statement has _{no label, the operator} must appear

first

in

the

statement.

A symbol used _{as an operator} must be _predefined by _{the assembler}

or the programmer before

its

first

appearance as an _operator in a

statement.

Operands

Operands _{are usually the symbolic addresses of the data to} be accessed when _{an instruction is executed, the names of processor}

registers to be used _{in the operation, or the input data or} arguments

to a pseudo-op _or macro

instruction.

In each _{case, the precise}

interpretation

of the operand(s) is dependent _{on the specific}

Chapter

I:

Introduction

commas, and _{are terminated} by _{a semicolon}

(;)

or a carriage

returri/line

feed.

Symbols used _as operands must have _{a valued predefined} by _the

assembler or defined by _{the programmer.} These _may be _symbolic

references to previously defined labels where _the arguments used by

this instruction

are to be _{found, or the} symbols _{may represent}

constant values or character strings.

Comments

The _{programmer may} add _{a comment to a statement} by _preceding

it

with a semicolon

(;)·

Comments _{are ignored} by the assembler but are

useful for documentation and

later

_{program debugging.} The comment _is

terminated by _{the carriage}

return/line

_{feed at the} end _{of the}

statement. In certain cases (eg. conditional assembly and _macro

definitions),

the use of the

left

and

right

square brackets

((I)

should be _{avoided in a} comment as

it

could

affect

the assembly

process.

An _{assembler statement may consist of}

just

a comment, _but each such _statement must _{begin with} a semicolon.

Statement Processing

The assembler _{maintains several internal} symbol _tables

for

recording the names and values of symbols used during the assembly. These _{tables are:}

I.

Macro _Table

-

This table contains

all

macros.

It

is

initially

empty, and grows as the programmer defines macros. 2. Op-Code _Table

-

This table contains

all

of the machine operation

mnemonics _{(op-codes), the assembler pseudo-operations}

(pseudo-ops), and _{user defined operators} (.OPSYNS).

It initially

contains the basic op-codes and _pseudo-ops, and _{grows as the} prograwrner provides additional

defínítions.

3. Symbol _Table

-

This table contains

all

programmer-defined symbols

other than those described above.

It initially

contains the standard register names, and then grows as new symbols _are

defined.

InternaZly,

all

of these tables occupy the saíne space, so that

all

of

the available space can be used as required. Order _of Symbol _Evaluation

The _{following table} shows _{the order in which the assembler}

searches the tables

for

a symbol appearing in each of the statement

fields:

Label Field:

PASM: PSA Macro

Chapter

I:

Introduction

Operator Field:

l.

Macro

2. Machine _operator 3. Assembler _operator 4. Symbol

Operand _Field:

l.

Number 2. Macro 3. Symbol

4. Machine _operator

Because _{of the}

different

_{table searching orders}

for

each

field,

_the same symbol could be used as a label, an _operator, and a macro, with no ambiguity.

Prograwmer-Defined Symbols

There _are two _type of programmer-defined symbols: labels and

assignments. As _{previously described,} labels _are generated by

entering a symbol followed by a colon (e.g. LABEL:

).

Symbols used as

labels cannot be _{redefined with a}

different

_value once they have been

defined. The _{value of} a label is the value of the location counter at the time the label

is

defined.

Assignments are used _{to represent, symbolically,} numbers,

bit

patterns, or character strings. Assignments simplify the program

development task by _{allowing a single source program modification}

(the assignment statement) to change

all

_{uses of that} number _or

bit

pattern throughout the _program. Symbols _{given values in an}

assignment statement 'ínay have new values assigned in subsequent

statements. The _{current value of an assigned} symbol _{is the}

last

_one

given to

it.

A symbol may be entered into the symbol _{table with}

its

_assigned

value by _{using a direct assignment statement of the form:} symbol _{= value}

{;

_or CR-LF}

where _{the value may be any}

valid

_{nuníeric value or expression.}

The _{value assigned to the} symbol _{may subsequently} be changed by

another direct asignment statement.

The _{following are valid assignment statements:} VALUEI _{= 23}

SIZE = 4*36 ZETA = SIZE

If it

is desired to

fix

the value assigned to a symbol so that

it

cannot subsequently be _{redefined, the direct fixed assignment}

statement should be used. _{This statement}

is

_{the same as the direct}

assignínent statement except that the symbol _{is followed} by two _equal

signs instead of one. For example: FIXED ₌₌ 46

NEWVAL

PSA Macro Assembler

Chapter

I:

Introduction

Assembly-Time Assignments

It

is often desirable _{to defer} the assignment of a _{value to} a symbol

until

_the assembly _{is actually} underway

(i.e.

_{not specify the}

value as _{part of} the source program). This is especially useful in setting program

origin,

buffer _sizes, and _{in specifying parameter}

values which

will

be used _{to control conditional} assembly _pseudo-ops. The PSA Assembler _{provides the}

ability

_{to specify} symbols _with

values to be _{determined at} assewbly _time, and _the mechanism by _which

the values may be

interactively

defined. To _{specify an assembly-time}

assignment, the following format is used: symbol _{=\ {svalue}}

where _{the svalue in braces indicates the optional specification of a} message _to be _output on the _{console device at} assembly _{time before}

requesting the symbo1"s _value. Any _{valid string value may} be

specified, including

multi-line

values.

After the optional message _{is output} on the console, a colon (:

)

is

output to indicate that the assembler is waiting for the desired value to be _entered. The _{value which}

is

_to be _{assigned to the} symbol

is

then input on the console device and the assembly continues with the symbol _{having the specified value. This interaction only occurs}

during the

first

assembly _pass. The _{symbol"s value remains} unchanged

during subsequent _passes.

Only _{numeric values rnay} be _{entered through the console in}

this

fashion. The nuuiber _{which is input} uiust _{conform to the} same rules as any other number used in the assembly _{source program,} and may be

followed by an optional radix modifier (see the section on Numbers

below). The number _is assumed _to be _{decimal unless followed} by _a

radix modifier.

The _{value being input}

is

_{not processed}

until

a carriage return

is

entered. Any _{mistyped character may} be _deleted by _{the use of the} DELETE _(or RUBOUT) key _(which

will

echo _{the deleted character) or the} BACKSPACE _(or CTL-H) key _which

will

backspace _{over the deleted}

character, and _{the entire} number _{may be deleted} by _entering CTL-U

(simultaneous use of the CTRL and the U key). Any character which

is

input but is not valid as _{part of} a number

will

be echoed as a BELL and

will

be _ignored.

The _{following are} examples _{of assembly-time assignment}

statements:

BUFSIZ =\ "BUFFER SIZE (50 TO 500 CHARACTERS)" DISK =\ "VERSION (O-PAPER TAPE I-DISK)"

Assembly-time assignment statements are similar to

direct

fixed assignments (==) _{in not allowing the} symbol _to be _{redefined elsewhere}

in the program.

Local and _Global Symbols

When _{assembling a large program,}

it

is

sometimes

difficult

_to keep _{track of the} symbols used

for

_{local data references} and

PASM: PSA Macro

Chapter

I:

Introduction

provides

for

both global and _local symbols _{within a single program.}

All

symbols _which

start

_with two periods _{are defined} as being

local,

and

all

_other symbols _{are global.} For example, _{the following are}

valid

local symbols:

..ABCD:

..1234:

0 0 0 *

A

particular

_{occurrence of a local} symbol _{is only defined within the}

boundaries of

its

enclosing global symbols. For example,

in

_the

following sequence of label

definitions,

the symbol ..SYML

is

only

defined (and _{can only} be _{referenced) within the} program between the

definition

of GLOBI and GLOB2:

0 * 9

GLOB!:

9 0 0

..SYMI:

0 0 0

GLOB2:

0 0 0

This

localization

of symbol

definitions

_{allows the} same symbol to be used _{unambiguously} more than once in the program.

It

also

simplifies

program understandability by immediately

differentiating

between

local and _{global symbols.}

In addition to labels, any other programwer-defined symbol maybe

specified as local (e·g? macros) in the same manner. Because of the

local usage of these symbols, they do _{not appear in the} symbol _table

listing

or in the symbol table optionally output to the object

file.

External, Internal, and _Entry Symbols

Programmer-defined symbols _{may also} be used _{as external,}

internal,

and _{entry point} symbols _{in addition to}

their

_{appearance as}

labels _{or in assignment statements.}

Symbols _which

fall

_{into one of these three groups are}

different

from other symbols _{in the prograrn} because _{they can} be _referenced by

other, separately assembled, _{program modules.} The _{manner in which}

they are used depends _{on where they are located:}

in

_{the program in}

which they are defined, _or in the program in which _{they are} a

reference to a symbol defined elsewhere.

If

the symbol _{appears in a program in which}

it

is defined,

it

must be _{declared as being available to other programs} by _{the use of}

the pseudo-ops .INTERN _or .ENTRY, _{or through the use of the}

delimiters

"""'

· " » "=""" ? "=="'" > _or

"_\:

"

in

their

definition

statements. These _{special delimiters are exactly equivalent to the} sequence:

Chapter

I:

Introduction

In each _{case, the delimiter is the normal} symbol

definition

_operator

(:

,

=, ==, =\) with an additional colon (:

)

added to indicate an

internal symbol

definition.

If

the symbol _{is located in a program in which}

it

is

a reference

to a symbol defined in another _program,

it

must be _{declared as}

external by _{the use of the} .EXTERN _{pseudo-op, or through the use of}

the "//" symbol _{modifier. This special} symbol _modifier

is

appended _to

the end _{of any} symbol _{to declare}

it

external. For example, _the

statement:

LXI H,SYMBOL//

is

exactly equivalent to:

.EXTERNAL SYMBOL

LXI H,SYMBOL Numbers

Numbers used _in a program _are interpreted by _{the assembler}

according to a radix (number base) specified by the programmer, where

the radix way be 2 (binary), 8

(octal),

10 (decimal), _or 16

(hexadecimal). The _{programmer uses the} .RADIX pseudo-op _{to set the}

radix

for all

numbers _{which follow.}

If

_the .RADIX _statement

is

_not

used, the assembler assumes a radix of 10 (decimal).

The _{radix may be} changed _{for a single} number by appending _{a radix}

modifier to the end _{of the} number. These _{modifiers are} B

for

binary,

O

or Q

for

octal, D or . (period) for decimal, and H

for

hexadecimal.

To _{specify the hexadecimal}

digits,

_the

letters

A _through F _are used

for

the values 10 _through 15 _decimal.

All

numbers, _however, inust

begin with a numeral. For exarnple, the following _{are valid} numbers: 10 tO

in

_{current radix}

10. 10 _decimal

IOB _{!0 binary} (2 _decimal)

OFFH FF _hexadecimal (255 _decimal) The _{following are invalid} numbers:

14B 4

is

not a binary

digit

FFH _the number must

start

with a numeral

Arithmetic and _{Logical Operations}

Numbers and _defined symbols _may be combined _{using arithmetic} and

logical

operators. The _{following operators are available:} + Add _{(or unary plus)}

-

Subtract (or unary minus)

* Multiply

/ Integer division (remainder discarded)

@ _{Integer remainder (quotient discarded)} & _Logical AND

Chapter

I:

Introduction

^ LogíoaZ _exclusive OR _{(or unary radix} change) //

Logical unary NOT

< Left _binary

shift

> _{Right binary}

shift

The _assembler cowputes _the

l6-bit

value of a series of numbers and

defined symbols connected by _{these operators.}

All

results _are truncated to the

left,

if

necessary. Two"s complement arithmetic is used, with the weaning _{of the sign}

bit

_(the most

significant bit)

being

left

to the programmer. Thís means that a numeric value may be

either between O _{and 65,535}

or between -32,768 and 32,767, depending

on whether

it

is signed or unsigned.

These _{combinations of} number and _defined symbols _{with arithmetic} and _{logical operators are} called expressions. When _{evaluating an}

expression, the assembler performs the specified operations

in

a

particular

order, as follows:

I.

Unary minus _{or plus (-} +)

2. Unary _radix change (^B "O "Q ^D ^H) 3. _Left and

right

_binary

shift

(< >) 4. _{Logical operators} (& !

"

//) 5. _{Multiply/Divide (* I)}

6. Remainder (@) 7. _Add/Subtract (+

-)

"Within each _{of the} above _{groups, the operations are performed from}

left

to

right.

For example, _{in the expression:} -ALPHA+3*BETA/DELTA&"H55

the unary minus _of ALPHA

is

done

first,

_then DELTA

is

ANDed _{with a}

hexadecimal 55, _then BETA

is

_multiplied by 3, _{the result of which}

is

divided by _{the result of the} AND, and

finally,

_{that result is} added

to the negated ALPHA.

To chaage _{the order in which the operations are performed,}

µarentheses rnay be used _{to "delimit} expressions and _to specify the

desired order of computation. Each _{expression within parentheses}

is

considered to be _{a single numeric value,} and _{is completely evaluated}

before

it

is

used _to compute any further values. For example, in the

expression:

4*(ALPHA+BETA)

the addition of ALPHA _to BETA

is

peformed _{before the}

multiplication

Radix Change _Operator

The _radix change _operator

is

used _{to temporarily} change _{the radix}

in

which a following number _{or expression is to} be interpreted.

It

is

written as an _up-arrow (") followed by the radix modifier of the desired radix. These _{modifiers are the sarne as those} used _{to specify}

the radix of a single number (B-binary, O

or Q-octal, D-decimal, and H-hexadecimal). The _radix change _{only affects the immediately}

Assembler

Chapter

I:

Introduction

all

of the following _are

valid

representations of the decimal number 33:

33. 33D ^033

^0(10*3+3)

^D(I0*THREE+THREE) ^DIO*^D3+"D3

but the following

is

not a representation of decimal 33

if

the prevailing radix is not decimal:

^D3*10+3

because _{the radix} change _{only affects the value immediately following}

it,

in

this

case 3.

Binary Shifting

The _binary

shift

_operators (<

left,

>

right)

are used to

logically shift

a 16-bit value to the

left

_or

right.

The number of

places to be _shifted

is

_specified by _{the value following the}

shift

operator.

If

that value is negative, the direction of the

shift

is reversed. For example,

all

of the following expressions have _{a value}

of 4 _decimal:

8>1 1<2 2>-1

One-byte Values

All

of the above _discussion has been based _{on the computation of}

l6-bit

(two _{byte) numeric values.} Many _{of the} Z80 _{operations require} an B-bit (one byte) value. Since

all

computations _are done as a

l6-bit

value, an operation calling

for

only eight

bits will

discard

the high order eight

bits

(the most

significant

byte) of the value.

If

the byte discarded

is

not either zero _or minus one

(all

one

bits),

a warning

will

be given on the assembly

listing.

Character Values

To _{generate a binary value equivalent to the} ASCU _{representation}

of a character

string,

the single

(")

_{or double (")} quotation mark

is

used. The _{character string is enclosed in a pair of the quotation}

marks. For example,

all

_{of the following are valid character values:}

"A"

PASbí: PSA Macro

Chapter

i:

Introduction

Note _{that whichever quotation} mark _is used _to

initiate

_{the character}

string must be used _{to terminate}

it.

If

_{the string} is longer than

two bytes,

it

is truncated to the

left.

Each

7-bit

ASCII _character

is

stored in an B-bit byte, with the high-order

bit

set to zero.

A _{character string of this}

type way be used wherever a numeric

value is allowed.

A _{single quote} may be used inside a string delimited by double

quotes, and _vice-versa.

If

it

is

necessary to use a single quote

within a string delimited by single quotes, two single quotes must be

used. The _{same is true for a double} quote in a string delimited by

double quotes.

Location Counter Reference

The _{location counter may} be _{referenced as a numeric 16-bit value} by _{the use of the} symbol _{. (period).} The _{value represented} by

.

is

always _{the Location counter value at the}

start

_{of the current} assembly _{language stateriient. For} example:

JMP _.

is an

effective

_{error trap,} jumping to

itself

continuously. Temporary _Variables

In addition to named _symbols,

it

is

sometimes _{convenient to} be

able to reference assembly _{time variables} by _{a numeric value or}

subscript. The PSA Macro Assembler _{allows the}

definition

_{of a single}

global assembly _{time array}

for

this

_{purpose. This array} has _the

special name

"*"

and is referenced by

"*[subscript]"

where subscript

is

any

valid

L6-bit absolute expression with a value between C) and

the number _{of array elements} minus

I.

_{This array reference may occur} anywhere _{a normal} symbol _{or label reference or}

definition is

_allowed. A _{temporary variable may} be _{assigned any numeric value, either}

absolute _{or relocatable,} within the normal

l6-bit restríctíon.

The

allocation of space for this _array

is

done by the .TEMPS pseudo-op

described

later.

For example: V=5

*[V]=4*V

W=5

MVI A,*[W]+23

String Variables

In addition to being able to assign a _{numeric value to} a symbol,

the PSA Macro Assembler _{allows a symbol to} be _{assigned a string value} as well. This

is

done through the .DEFINE pseudo-op _{in the same} manner in which a macro is defined (see Chapter _{4), except that}

defined string variables may have no _arguments. A string variable

may only be DEFINEd _{once in a program. String variables may} be used anywhere _{a string value is called}

for

_{(eg. the .ASCII pseudo-op).}

PSA Macro

Chapter

l:

Introduction

.DEFINE PR0MPT=[>>]

.ASCII "ENTER N1JMBER",PROMPT

Substring Operator

It

is sometime _{desirable to obtain a substring of a given}

string,

macro argument _{or string} variable. The PSA Macro Assembler _provides

that capability through the use of the substring _operator "<". The

format

for

the use of

this

operator

is:

<[s{,L}]dtextd

or

<[s{,l}]svariab1e

where s is a 16-bit expression whose _{value is the starting character}

to be used, and

I

_{is an optional L6-bit expression}

for

_{the length of}

the string _{to use.} The

first

_{string character}

is

O.

If

the length

is

omitted, the entire rest of the string

is

used.

The

first

_{form uses a delimited string as}

its

_{string argument.}

the d _{represents a delimiter which may} be _{any character not contained}

within the string

itself.

The _string argument _starts with the

first

character

after

the delimiter, and _{terminates with the}

last

_character

before the corresponding

delimiter.

The _{delimiters are not part of}

the

string.

If

the

initial

delimiter

is

a

left

bracket

(I),

then the matching delimiter is a

right

bracket

(I).

The

left

and

right

brackets _{are paired,} so that intervening pairs of

left

and

right

brackets

will

not terminate the

string.

The second _{form uses a string variable as}

its

_{string argument.} For example:

.DEFINE STRNG1=[THIS IS STRING ONE]

.ASCII <[0,I]STRNGL

.ASCII <[5,3j"0l23456789"

The _{substring operator may also} be used _{in a normal arithmetic}

expression in place of a single _or double character value. For example:

MVI A,<[V,lj"0l23456789"

String Length Operator

It

is often quite _necessary to use the length of a given string

value as a value in an numeric expression. To

facilitate

this,

the

string length operator "@" is provided.

It

is used by _prefixing

it

to the

front

of the string value whose _length

is

_desired, and _{may be} used anywhere _{an absolute} number _{is allowed.} For example:

.DEFINE STRNGI=[THIS IS A STRING] MESSI: .ASCIZ STRNGL

Chapter

I:

Introduction

String Values

Many pseudo-ops

utilize

_{a generic}

"string

_{value" argument.} A

string

value is either a delimited string (see Substring Operator

above), a string variable _or a substring operation. For example,

all

of the following _{are valid} string values (assuming STRNGL

as defined

above):

STRNGL

"THIS IS A STRING"

[THIS IS A [BRACKETED] DELIMITED STRING]

PAM:

Chapter 2: _Addressing and _Relocation

Chapter 2

Addressing and _Relocation Address Assignment

As _{source statements are processed} by _{the assembler, consecutive} memory addresses are assigned to the

instruction

and _{data bytes of}

the object _program. This is done by _{incrementing an internal program}

counter each _{time a memory byte}

is

_assigned. Some _{statements may}

increment

this

internal counter by _{only one, while others could}

increase

it

by _{a large} amount. Certain pseudo-ops and

direct

assignment statements have _{no effect on the counter at}

all.

In the program

listing

generated by the assembler, the address assigned to every statement

is

shown.

Relocation

The PSA Macro Assembler

will

_{create a relocatable object program.}

This program may be loaded into any _{part of} memory as a function of

what has been _{previously loaded.} To _accomplish

this,

_certain

l6-bit

values which represent addresses within the program must have _a

relocation constant added _to them. _{This relocation constant,} added when _the program is loaded into memory,

is

the difference between _the memory location an instruction (or piece of data)

is

actually loaded

into,

and _{the location}

it

was assembled _at.

If

an

instruction

had been assembled _{at location} lOó _(decimal), and _{was loaded into}

location 1100 _{(decimal), then the relocation constant} would be 1000

(decimal).

Not

all

_{L6-bit quantities} must be _modified by _{the relocation}

constant. For example, _the

instruction:

LXI H,0OFFH

references a

i6-bit

quantity (OOFFH) which does not need _relocation. However, _{the set of instructions:}

JZ DONE 0 0 e

DONE:

does _reference a

l6-bit

quantity (the address of DONE) which must be

relocated, since the physical location of DONE _{changes depending}

on where _{the program is loaded into} memory.

To _{accomplish this} relocation, the 16-bit value forming an

address reference is marked by _{the assembler}

for later

_modification by _{the loader or linkage}

editor.

Whether _{a partícular}

l6-bit

_value

is

so marked depends on the evaluation of the arithmetic expression

from which

it

is obtained. A _{constant value (integer) is absolute}

Chapter 2: _Addressing and _Relocation

relocatable (assuming _relocatable code

is

_being generated), and _are always _modified by _{the loader or linkage}

editor.

Symbolic references

way be either absolute _{or relocatable.}

If

a symbol is defined by a

direct

assignment statement,

it

may be _{absolute or relocatable} depending _{on the expression} following the equal sign (=).

If

the symbol

is

_{a label} (and _relocatable code

is

being generated) then

it

is

relocatable.

To _{evaluate the}

relocatability

of an expression, consider what happens _{at load or linkage} edit time. A _{relocation constant,}

r,

must be added _to each _{relocatable element,} and _{the expression evaluated.}

For example, _{in the expression:}

Z

= Y+2*X-3*W+V

where V, W, _{X, and} Y

are relocatable. Assume that r

is

the relocation constant. Adding

this

constant to each _{relocatable term,}

the expression becowe.s:

Z(r) = (Y+r)+2*(X+r)-3*(W+r)+(V+r)

By _{rearranging the expression, the following is obtained:}

Z(r) = Y+2*X-3*W+V + _r

This expression is suitable for relocation because

it

contains only a

single addition of the relocation constant

r.

In general,

if

the expression can be rearranged _{to result}

in

the addition of either of

the following,

it

is

legal:

O*r _{absolute expression}

l*r

relocatable expression

If

the rearrangement results in the following,

it

is illegal:

n*r where _n

is

_not O

or I

Also,

if

the expression involves

r

to any power other than

l,

it

is

illegal.

Thís leads to the following rules:

l.

Only _{two values of}

relocatability for

_{a complete expression are}

allowed

(le.

n*r where _{n =} O

or

I).

2. _Division by _{a relocatable value}

is illegal.

3. Two _{relocatable values may not} be _{multiplied together.}

4. _{Relocatable values may not} be combined by

logical

_operators. 5. A _{relocatable value may not} be

logically

_shifted.

If

any of these rules

is

broken, the expression

is

illegal

and _an

error message is given.

If

X, Y, and Z

are relocatable symbols, then:

X+Y-Z

is

_relocatable

X—Z

is

absolute

X+7 _{is relocatable}

PSA Macro Assembler

Chapter 2: _Addressing and _Relocation 4&X-Z

is illegal

Only

l6-bit

_{quantities may} be _relocated.

All

_{B-bit values inust} be

absolute _or an _error

will

be _given.

Relocation Bases

One _{of the unique capabilities of the} PSA Macro Assembler _is

its

ability

to handle symbolic references to separately located _{areas of}

memory, where _the mapping _of symbols _{to physical addresses occurs at}

linkage edit time. The _{symbolic names}

for

_{independently located} memory _{areas are} called "relocation bases". These _relocation bases inay represent ROM

vs. RAM, shared COMMON areas, special memory _areas such _{as video refresh, memory} mapped _{I/O, etc. Within} each

subprogram, each _{of these mewory areas}

is

_referenced by _{a unique} name, with the actual allocation deferred to the

link

edit and' _load

process.

All

memory references within the assembled program _are

relative

to one of these relocation bases.

As each _relocation base _{is assigned a name in the program}

(through the use of the .EXTERN pseudo-op),

it

is

implicitely

assigned a sequential identifying number. This number appears in the

listing

as part of any address

relative

to that base.

Four _{of these relocation} bases _(0-3) have _{predefined names} and

meanings, and _{are treated}

differently

_{at linkage edit time than the}

remainder of the bases. Base D

represents absolute memory locations

(le.

it

always has _{the value of} O). Base L _{has the}

name .PROG. and

represents the program _area (maybe PROM _or ROM). Most program code (and _{data in} non-romned programs)

is

_generated

relative

_to

this

relocation base. Base 2 _{has the}

name .DATA. and _represents the local data area

for

each uíodute. Most _{local data is defined}

relative

_to

this

base. Base 3 _{has the}

name .BLNK. and _represents the global

"blank common". _{This relocation} base _is always _{assigned the value of}

the

first

free byte in memory

after

the local data storage (.DATA.) and _{other data relocation} segments by _{the Linkage}

editor.

Because

it

is

always _the

last

_allocated, modules _referencing

this

_{area can} be

included in any order, regardless of the amount _{of the area they use.}

Relocation segments

relative

_to bases _I and 2 _{(.PROG. and .DATA.)}

are always allocated additively

(íe.

after

each module

is

allocated, the value of the relocation base _{is increased} by _{the size of the}

segment).

All

other relocation bases _{are normally} assumed _to have

constant values during the allocation _{process (usually} assigned by

the linkage

editor).

Each symbol _{defined during the} assembly has _{a relocation} base

associated with

it.

There _{are no}

limitations

_{on inter-base}

references

(le.

code

relative

_to .PROG. _can

freely

_{reference data}

relative

to .DATA.). Expressions containing symbols must _{evaluate to} a value

relative

to a single relocation base, but may contain

references to multiple relocation bases.

All

relocation base

references except

for

the

final

result must be _part of sub-expressions which evaluate to absolute values. For example,

if

T

and U

are symbols

relative

to base

I,

V _and W

relative

to base 2, and X and Y

PASM: PSA Macro

Chapter 2: _Addressing and _Relocation

T+(V-W) _{(note the parentheses to} make V-W a subexpression)

X+3

T-(V-W)*U+(X-Y)

and _{the following are}

invalid:

T+U _{(within a relocatiori base, the}

normal relocation rules apply)

T-l-V-W (T-l-V

is

_the

first

subexpression,

and

it

is mixed _relocation bases)

It

should be _{noted that conceptually, normal external} symbols _are

simply relocation bases _{with a size of zero (O),} and _{the assembler}

treats them _{that way.} An _{assignment of the form:} N==P+5

where P

is

an external symbol, makes N

a symbol whose address is

relative

to P, even though P _{has no size. Hence, expressions of the}

form:

5*(P-N)

where P _and N _{have the}

PSA Macro

Chapter 3: _{Pseudo-Operations}

Chapter 3

Pseudo-Operations

Pseudo-operations _{(pseudo-ops) are directions to the assembler to} perform certain operations

for

the programmer, as opposed _to machine

operations which _are instructions to the computer. Pseudo-ops

perform such _{functions as}

listing

_{control, data conversion,}

or storage

allocation.

Address MOde and _Origin

The PSA Macro Assembler _normally assembles _programs

in

relocatable mode, _{so that the resultant program can} be _loaded anywhere _{in memory}

for

_{execution. Therefore,}

all

_{programs are} assembled assuming

their

first

_{byte is at address zero (O),} because

they can be relocated anywhere. When desired, however, _{the assembler}

will

generate absolute object code, _either

for

_{the entire program, or}

just

selected portions. The _assembler

will

_{also locate the} assembled code _at any address desired. The two pseudo-ops _{which control}

address mode, _relocation base and _address

origin

_are .LDC and .RELOC. .LOC _n

This statement sets the location counter to the value n, which

may be any

valid

expression.

If

n

is

an absolute value, then the

assembler

will

assign absolute addresses to

all

of the instructions

and _{data which follow.}

If

n is relocatable, then relocatable addresses

will

be _assigned,

relative

_{to the relocation} base _{of the}

expression.

The _{program is} assumed _{to to}

start

_{with an}

implicit

.LOC _to

relocatable address _zero (O) _{of the relocation} base named .FROG.

(the default relocation base

for

_{normal programs).} Él

program can

contain wore than one .LDC, each controls the assignment of addresses

to the statewents following

it.

To _{reset the} program _{counter to}

its

value

prior

to the

last

.LDC,

the statement:

.RELOC

is

used. This statement restores both the value, the relocation base and _{the addressing} mode _which were in effect before the immediately preceding .LDC.

If

_no .LDC has been done, _{then a} .RELOC

is

equivalent to a: .LDC O

When _{in relocatable addressing} mode, _{the assembler}

will

_determine

whether each

I6-bit

_value

is

_{absolute or relocatable} as described in

PASM: PSA Macro

Chapter 3: _{Pseudo-Operations} Data

Definition

The PSA Macro Assembler _provides a number of

different

pseudo-ops

for

describing and _{entering data to} be used by _{the program.} .RADIX

When _{the assembler encounters} a number in a statement,

it

converts

it

to a

l6-bit

binary value according to the radix

indicated by _{the programmer.} The _statement: .RADIX _n

where _{n is} 2, 8, ID, _or 16, _{sets the radix to n}

for all

numbers

which follow, unless another .RADIX _{statement is encountered, or}

the radix

is

modified by _the

"r

_{operator or a}

suffix

_radix

modifier.

The _statement: .RADIX 10

implicitly

begins each assembly _{program, setting the}

intial

_radix

to decimal.

.BYTE

To _{enter one (or} more) B—bit (one _{byte) data values into the}

program, the statement:

.BYTE

{[r]}n {, {[r]}n

·..}

where

r

is an optional _{repeat count which} can be any 16-bit value

(including O) and _{n is} any expression with a valid B-bit value,

is

used. More _{than one byte can} be _{defined at a time} by

separating

it

from the preceding value with a comma.

All

of the

bytes defined in a single .BYTE statement are assigned consecutive memory locations. For example:

.BYTE 23,4*^HOFF,BETA-ALPHA,[5]0

defines three sequential bytes of data.

.WORD

To _{enter a}

l6-bit

(two _{byte) value into} the _{progratn, the}

statement:

.WORD

nn

{,

nn

...}

where _nn

is

_{any expression with a valid}

l6-bit

_value,

is

used. Multiple

l6-bit

values may be defined with one .WORD

statement by

separating each _{from the preceding one with a comma.}

All í6-bit

values defined by _the .WORD _pseudo-op

are stored

in

standard Z80 word _{format, least}

significant

_byte

first.

Chapter 3: _{Pseudo-Operations}

.WORD ALPHA,234'U3ETAJHOEEFF

defines three sequential

l6-bit

values, _or a

total

of six 'bytes of data.

.ASCII, .ASCIZ, and .ASCIS

To _{enter strings of text characters into the program,} one of the stateuients:

.ASCII s l [n] .ASCIZ _s l _[n]

.ASCIS _s I _[II]

is

used. The _{s represents any}

valid

_{string value.} Each

character in the text

is

converted to

its

7-bit

ASCII

representation (with the eighth

bit

zero), and _{stored in}

sequential memory locations. The string value may be followed by

another string value (seperated by _{an optional} comma), and

this

may be repeated as desired.

If it

is

necessary to include values

in

the text

string for

which no character exists, then the second option shown above may be _used.

If

_{in place of a string value, the assembler finds a}

left

square bracket

(I),

then the numeric expression enclosed

within

it

and _{a matching}

right

_{square bracket}

(I)

_{is evaluated as} an B-bit value and stored as the next byte of the

string.

These

B-bit values may be intermixed with stríng values as required

(optionally seperated by commas). Note _that

this

_{precludes the} use of bracketed delimited strings as string values in these statements.

It

is important to note that tab, carriage return, and

line

feed are

all

valid characters within a string value.

It

is

therefore possible that a .ASCIX statement

will

encompass more

than one

line

in the source program.

The _difference between _{the three} pseudo-ops _described above

is

in

their

treatment of the

last

byte generated by _the

statement. The _{.ASCII statement}

just

_{stores the byte.} The .ASCIZ _{statement stores one additional byte}

after

_the

last

one, a

null

(zero) byte to mark _the end _{of the string in memory.} The .ASCIS pseudo-op sets the high-order (eighth)

bit

of the

last

byte to one to flag the

last

byte.

The _{following are}

all

_valid .ASCIx _statements:

.ASCII /This

is

a

string/

.ASCIZ _/This

is

two/ "

strings in one place" .ASCIS [^H0D] [^H0A] "Message _{on new}

line"

.ASCII \

Message on new

line\

.ASCII PNAME

.string

variable plus

string.

.ASCIZ _{<[2,B]"substring} expression"

.RAD40

The _{Radix-40 character set}

for

symbols _was chosen because

it

PASN: PSA Macro

Chapter 3: _{Pseudo-Operations}

character set, the statement:

.

.RAD40 _{symboll {,} symbo12

...}

is

used. The symbol must _{conform to}

all

the rules specified for

assembler symbols, and _{is converted into} the Radix-40 notation

and _{stored in four} sequential bytes of memory.

If

multiple symbols _{are to} be converted and _stored, each must be _separated

from the preceding one by a comía.

Storage Allocation

The PSA Macro Assembler _{allows the} programmer _{to reserve single}

locations, or blocks of many locations,

for

use during the execution

of the program. The two pseudo-ops used

for

this

_{purpose are} .BLKB and .BLKW. The _{format of the statement using these} pseudo-ops

is:

.BLKx _n

where _{n is the} number _{of storage locations to} be _reserved.

For the .BLKB _pseudo-op, each _{storage location consists of} one

byte, so the above statement

will

reserve n contiguous bytes of memory, starting at the current location counter. The .BLKW pseudo-op _{uses a word} (two _{bytes) as}

its

_storage

unit,

_{so the} above

statement would _{reserve n words, or} two _times n bytes of contiguous memory.

For exampLe, each _{of the following statements reserves} 24

(decimal) bytes of storage:

.BLKB 24. .BLKW _^Dl2 .BLKB _2*12.

Temporary _Variables

The PSA Mácro Assembler _{allows the allocation of temporary}

variable _arrays

for

use during the assembly _process. These _arrays may be used. both on a global basis, and within macro expansions. The use of these arrays in each _{of these contexts is described elsewhere}

iri this manual. The _{actual allocation of space}

for

_{these arrays}

is

done _{usírig the} .TEMPS _pseudo-op. The _{format of}

this

_statement

is:

.TEMPS n

where _{n is a}

i6-bit

_{value specifying the} number _{of array elements to}

allocate.

This statement may appear anywhere in the _program, and _{may be} used _{more than once. In either context (global or macro), the}

PSA Mácro Assembler

Chapter 3: _{Pseudo-Operations} Program _Termination

Every program must be _terminated by _a .END _pseudo-op. The _format

of

this

statement

is:

.END

start

where

start

_{is optional an starting address}

for

_{the program.} The

starting

address

is

normally _{only necessary}

for

the main _program. Subprograms, _{which are called frotn the wain program,} need _no

starting

address.

When _{the assembler encounters the} .END pseudo-op _{during pass ! of}

the assembly,

it

initiates

pass 2 of the assembly. On

a

listing

pass, the .END pseudo-op

initiates

_the

printing

_{of the} symbol _table

(if

not suppressed by _a

prior

.XSYM _pseudo-op). On

a object

producing _{pass, the} .END pseudo-op _{output the} EOF _record

to the object

file.

Subprogram _Linkage

Programs _{usually consist of a wain program} and _numerous

subroutines which communicate _with each _{other through parameter}

linkages and _{through reference to} symbols _{defined elsewhere in the}

program. Since the PSA Macro Assembler _{provides the means}

for

_the

various program components _to be assembled _{separately from} each

other, the linkage editor (which

finally

puts the pieces together)

must be _{able to}

identify

_those symbols _{which are references (or}

referenced) external .to _{the current program} For _{a given} subprogram,

these "linkage" symbols _{are either} symbols _defined

internally

_which must be _{available to other programs to reference, or} symbols used

internally

but defined externally to the program. Symbols de'fined within the program but available _to other subprograms _{are called}

"internal"

symbols. Symbols used

internally

_{but defined elsewhere}

are called "external" symbols.

To _set up these linkages between subprograms, four pseudo-ops _are

provided: .IDENT, .EXTERN, .INTERN, and .ENTRY. The .IDENT _statement has _{the format:}

.IDENT symbol

where symbol _{is the relocatable} module _{name. This name}

is

used by

the linkage editor to

identify

the module _{on memory allocation maps,} and _{to allow the selective loading of the} module

if it

is

part of a subprogram

library.

If

_the .IDENT _statement does _{not appear}

in

_a

program, the nane ".MAIN." is asstuned. The .IDENT name appears at the top of every

listing

page, and is displayed on the console at the

start

of the second assembly _{pass of that} module.

All

three remaining statements have _the same format:

Éíácro

Chapter 3: _{P"eudo-Operations}

where _syriiboll

is

_the symbol _{being declared} as external,

internal,

_or as an entry point. Multiple symbols _may be _{declared in the} same

statement by _separating each _{from the preceding} one with a comma. The .EXTERN _statement

identifies

symbols _{which are defined}

elsewhere. External symbols must _not be _{defined within the current}

subprogram. External symbols _ínay be used _{in the same} manner as any

other relocatable symbol, _{with the following}

restrictions:

l.

The _{use of more than one external} symbol

in

_{a single expression}

is

illegal.

Thus V+W _where V _and W

are both external is

illegal.

2. _{Externals way only} be _{additive. Therefore the following}

expressions are

illegal

(where V

is

an external symbol): -V

2*V SQR-V 2*V-V

3. The

final

_{evaluation of the expression containing the external}

reference must result in external symbol + (or —)

constant value. Furthermore,

if

this

expression is used _as an B-bit (byte) value,

the constant must be between _-128 and +255 _{or an error}

will

result.

SywboLs _{deciared as external} by _the .EXTERN pseudo-op _{may also} be used _{as relocation bases. This is} done by _{using an external} symbol as the argument _to a .LOC pseudo-op.

All

memory allocated by the

assembler

after

the .LDC

will

be addressed

relative

_{to the specified}

relocation base. The most common use of

this

capability

is

the

declaration of COMMON _blocks

for

the sharing of data between

assembler arid FORTRAN _subprograms.

All

named COMMON _blocks

are in fact

just different

relocation bases. Symbols used _{as relocation} bases have _{unique values during the} assembly _{of the program} module. At _{any point in time, the current value of the relocation} base symbol

is

the number _{of bytes which} have been _{allocated to that} base _so

far.

This means that subsequent .LDC pseudo-ops _{referencing the same}

external syiíbol