.FI;AD;LM 10;RM 70;SP 5;CE
@RAG @SOFTWARE
.SP 2;CE
@TI^99/4A @MACRO @ASSEMBLER
.SP 2;CE
@Version^7
.SP 2;CE
@ASSEMBLER^LANGUAGE^REFERENCE
.SP 6;IN +11
@CONTENTS


COMPATIBILITY ......................^ 1

^^^Unsupported Features ............^ 1
^^^Extensions ......................^ 1

ELEMENTS OF THE LANGUAGE ...........^ 2

^^^Assembler Statements ............^ 2
^^^Assembler Symbols ...............^ 3
^^^Macro Symbol Substring Notation .^ 4
^^^Macro Definitions ...............^ 5
^^^The Location Counter ............^ 5
^^^Expressions .....................^ 6
^^^Constants .......................^ 7
^^^Definition of Terms .............^ 7

ASSEMBLER DIRECTIVES ...............^ 9

ORDINARY STATEMENTS ................^15

MACRO DIRECTIVES ...................^34
.IN +0;SP 8
This manual and the TI 99/4A Macro
Assembler program are copyright
(c) 1988 by RAG SOFTWARE.


September 1988
.BP;PA 2;CE
@ASSEMBLER^LANGUAGE^REFERENCE
.HE ^^^^^^^^^^^^^^^^^^^^^^^^^^^TI^99/4A^Macro^Assembler^^^^^^^^^^^^^^^^^^%
.SP 2
This manual is a reference for the
language supported by the Macro
Assember.
.SP 2
@COMPATIBILITY

The TI 99/4A Macro Assembler, with the
exceptions noted below, is compatible
with the Assembler Language described
in the TI Editor/Assembler manual for
the TI 99/4A.

@Unsupported^Features

The following Instructions are not
assembled: CKON, CKOF, IDLE, LREX,
RSET.

The following Assembler Directives are
not supported: CEND, CSEG, DEND, DSEG,
DXOP, LOAD, PEND, PSEG, SREF.

The DORG directive is supported only
with an absolute expression as the
operand.

@Extensions

The TI 99/4A Macro Assembler has
several extensions to the TI Assembler
Language and syntax.

First, the macro facility is a major
extension.  The macro facility includes
the ability to define new instruction
operation codes as well as define macro
instructions.

Second, three new assembler directives:
EQUV, OBJREC and STRI have been added
to the language.

Third, a quoted string may use either
single or double quotes as the string
delimeter.  In either case, if the
delimeter is to occur within the string
it must be represented by a pair.  A
string may also specified as a sequence
of hexadecimal digits preceeded by the
">" usually used to indicate hex
constants.

Fourth, COPY statements may use an
asterisk as the disk number.  This is
used to tell the assembler that the
copy file is on the same disk as the
source file.  For example:
.SP;IN +10
COPY 'DSK*.PARTB'
COPY "DSK*.PARTC"
.SP;IN +0
Both are valid copy statements
indicating that the files PARTB and
PARTC are on the same disk as the
source file specified at the beginning
of the assembly.

Fifth, the characters, number sign (#),
dollar sign ($), percent sign (%) and
underscore (_) may be used as the
second or following characters of
assembler symbols.
.SP 2
@ELEMENTS^OF^THE^LANGUAGE

In order to understand and use the
assembler language there are a number
of definitions and conventions that
must be understood.

@Assembler^Statements

Each line of Assembler code is called a
statement.  There are five types of
statements, each of which is defined
below.

&COMMENT -- these statements provide
notes for the person reading the code.
The assembler ignores comments except
for printing them in the listing.
Comment statements are identified by an
asterisk in position one of the
statement.

&ASSEMBLER^DIRECTIVES -- these
statements give the assembler
directions on how you want your code
assembled.  Assembler directive
statements have the following format.
.SP;IN +5
[label] operation operands [comment]
.SP;IN +0
Each of the four fields in the
statement are separated by one or more
blanks or spaces.  The label and
comment fields are always optional.
The label if present must begin in
position one of the statement.  If no
label is coded, at least one blank must
precede the operation field.  Some
assembler directives have no operands
in which case the comment field
immediately follows the operation
field.  Individual operands within the
operands field are separated from each
other by commas.  No blanks must occur
within the operand field unless the
operand is enclosed in quotes.  The
operation field names the assembler
directive.  All the assembler
directives are described later.

&MACRO^DIRECTIVES -- these statements
give the assembler directions on how to
interpret and assemble your macros.
Macro directives occur only within a
"macro definition".  NOTE that the
$OPCODE directive is described as a
macro directive although strictily it
is not.  Macro directives have the
format shown below.

^^^^^$operation operands [comment]

Each of the three fields in the
statement are separated by one or more
blanks or spaces.  Macro directives are
recognized by the dollar sign coded in
position one of the statement.  The
comment field is always optional.  Some
macro directives have no operands, in
which case the comment field
immediately follows the operation
field.  Individual operands within the
operands field are separated from each
other by commas.  No blanks must occur
within the operand field unless the
operand is enclosed in quotes.  The
operation field names the macro
directive.  All the macro directives
are described later.
.BP
&ORDINARY^STATEMENTS -- these
statements represent machine
instructions which are to be assembled.
The bulk of your code will be ordinary
statements.  Ordinary statements have
the following format.

^^^^^[label] operation operands [comment]

Each of the four fields in the
statement are separated by one or more
blanks or spaces.  The label and
comment fields are always optional.
The label if present must begin in
position one of the statement.  If no
label is coded, at least one blank must
precede the operation field.
Individual operands within the operands
field are separated from each other by
commas.  No blanks must occur within
the operand field unless the operand is
enclosed in quotes.  The operation
field names the machine instruction to
be assembled.  All of the predefined
machine instructions are described
later.  Some machine instructions have
no operands in which case the comment
field immediately follows the operation
field.  The $OPCODE directive can be
used to define new machine
instructions.

&MACRO^STATEMENTS -- these statements
cause a macro to be invoked.
Statements "generated" by a macro are
assembled as though they appeared in
the source file.  Macro statements look
just like ordinary statements as shown
below.

^^^^^[label] operation operands
[comment]

The operation field names the macro
definition that is to be used.  The
interpretation of the label field and
the operands field is completely
controled by the macro definition.

@Assembler^Symbols

There are two kinds of assembler
symbols.

&ORDINARY^SYMBOLS -- these symbols
represent memory addresses or data
values.  Ordinary symbols are defined
by appearing in the label field of an
ordinary statement, an assembler
directive statement or in the operand
field of a REF directive.  The value of
an ordinary symbol is a 16-bit unsigned
number.  Unless otherwise specified,
the value assigned to a symbol is the
current location counter at which the
statement is assembled.

Ordinary symbols are 1 to 6 characters
in length.  The first character must be
a letter, "A" to "Z".  The second and
following characters can be a letter
(A-Z), a number (0-9) or one of the
characters "$", "#", "%" or "_".

&MACRO^SYMBOLS -- these are special
predefined symbols used within a macro
definition.  The value of a macro
symbol is a character string with a
length of 0 to 60 characters.  The
names of the macro symbols are of the
form &&tn.  Where the ampersand
identifies a macro symbol.  If you wish
to code an ampersand that is not part
of a macro symbol name within a macro
definition you must code a pair of
ampersands.  The "t" in the macro
symbol name is the type of symbol.
There are four types of macro symbols:
"P" for Parameter macro symbol, "L" for
Local macro symbol, "G" for Global
macro symbol and "S" for System macro
symbol.  The "n" in the macro symbol
name is a single digit from 0 to 9.
Thus each type has ten different
symbols and there are 40 macro symbols
in total.

Parameter macro symbols have as their
values the label field and the operands
of the macro statement that invoked the
macro.  &&P0 contains the label field,
&&P1 contains the first operand, &&P2
contains the second operand, and so on.
A macro statement can therefore have a
maximum of 9 operands.

System macro symbols have values
assigned by the assembler.  These are:
.SP;LM +10;IN -6
&&S0^=^value from the OPTIONS prompt.
&&S1^=^the number of macros processed
so far in the assembly.  This value is
useful for generating unique names
within macros.  The number is
represented as a five character string
with leading zeros.
&&S2^=^the number of operands on the
macro statement.  The number is
represented as a five character string
with leading zeros.
&&S3^=^a single character, "1"
indicating the first pass of the
assembler and "2" indicating the second
pass of the assembler.  
&&S4^=^the information entered for the
ID/DATE prompt.
&&S5^=^the source file name.
.LM -10;IN +0;SP
The remainder of the system macro
symbols are currently not used and have
a null value.

Local macro symbols have values set via
the $SET macro directive.  All local
macro symbols are reset to null at the
beginning of each macro invocation.

Global macro symbols have values set
via the $SET macro directive.  All
global macro symbols are reset to null
at the beginning of each pass of the
assembler.  Global symbols can be used
to communicate from one macro
invocation to another within the same
assembler pass.

@Macro^Symbol^Substring^Notation

Substrings of the macro symbol values
are allowed.  The general form for a
macro symbol with substring notation
is: &&tn(s.l).  Where "s" is the
starting position for the substring and
"l" is the length of the substring.
Note that "s" and "l" are separated by
a period not a comma.

As is usual for substring notation, if
"s" specifies a position past the end
of the string a null string will
result.  Also, if "l" specifies a
length greater than the remainder of
the string only the remainder is used.
The "l" and the period are optional.
If only "s" is specified then the
remainder of the string is used.

Assume that the macro symbol &&L2 has the value
'ABCDEFGHIJKLMNOPQRSTUVWXYZ', then:
.IN +5;SP
&&L2(25)^^^^has the value 'YZ'
&&L2(1.4)^^^has the value 'ABCD'
&&L2(24.8)^^has the value 'XYZ'
&&L2(27.8)^^has the value ''
.IN +0;SP
There are cases where you may want a
macro symbol to be followed by a
bracketed expression that is not
substring notation (i.e. in an indexed
symbolic memory reference).  This can
be done by following the macro symbol
with a period such as: &&L2.(2).  In
fact any period following a macro
symbol will be considered part of the
macro symbol name and will be removed
when the value of the macro symbol is
substutited.

@Macro^Definitions

The macro faciltiy gives you a
shorthand way of coding assembler
language programs.  It can also be
thought of as providing you with a
slightly higher level of language (i.e.
a language level somewhere between pure
assembler and, say, BASIC).  Usually,
coding a single macro statement will
cause several ordinary assembler
statements to be generated and
assembled into your program.

If you find yourself repeatedly coding
the same group or sequence of
statements with only slight
differences, these could be coded
within a macro definition and then
replaced in your source programs by a
single macro statement.  This reduction
in the number of statements in your
program has several advantages.  The
source program is smaller thus easier
to read and understand.  Once the code
generated by the macro is debugged then
you need not debug each occurrance of
it in your program.  Less statements
means less typing and less errors.

Macro definitions can be placed in the
macro file or can be placed in the
source file.  Macro definitions in the
source file must precede the first use
of the macro.

A macro definition consists of macro
directives, ordinary assembler
statements or assembler directives.  No
macro statements may occur within a
macro definition.  During macro
processing, the macro directives are
executed by the assembler.  Ordinary
assembler statements and assembler
directives are scanned and any macro
symbols are replaced by their values.
After replacement of macro symbols, the
ordinary statements and assembler
directives are assembled just as though
they were read from the source file.

A macro definition must begin with the
$MACRO macro directive and end with the
$END macro directive.

@The^Location^Counter

The Assembler maintains a "location
counter" (similiar in purpose to the
computer's Program Counter) as it
assembles code or data.  This location
counter is the "address" at which the
code or data will be loaded.  The
location counter value may be either
relocatable or absolute.  If absolute,
then the location counter is the exact
memory address at which the code or
data must be loaded.  If relocatable,
then the location counter is a
"relative address" that is, relative to
the address at which loading starts.

The Assembler begins with its location
counter at zero and in relocatable
mode.  The AORG, RORG and DORG
Assembler Directives can be used to
assign values to the Assembler's
location counter.  As symbols are
encountered in the source code, they
are assigned values usually based on
the location counter.  Along with the
value assigned, each symbol has an
attribute of "absolute" or
"relocatable" depending upon how the
symbol was assigned a value.

The value of the Assembler's location
counter can be referenced by the
special symbol "$".

@Expressions

The Assembler allows the use of an
arithmetic expression for most operands
("string" operands are an exception).
These expressions can contain ordinary
symbols, constants and the operators:
"+", "-", "*" and "/".  Expressions are
evaluated in strict left to right order
with no operator precedence rules.  For
example, "2+3*5" evaluates to 25 not to
17 as would a BASIC expression.
Parentheses are not allowed in
Assembler expressions.

All expressions are evaluated using
16-bit unsigned arithmetic.

When ordinary symbols are used in
expressions it is important to keep in
mind the relocatibility attribute of
the symbols.  The relocatibility rules
for expression evaluation are:
.SP;IN +5
relocatable + relocatable ^is^ not allowed
relocatable + absolute^^^^^is^ relocatable
absolute ^^ + relocatable^^is^ relocatable
absolute ^^ + absolute^^^^^is^ absolute

relocatable - relocatable ^is^ absolute
relocatable - absolute^^^^^is^ relocatable
absolute ^^ - relocatable^^is^ relocatable
absolute ^^ - absolute^^^^^is^ absolute

relocatable * relocatable ^is^ not allowed
relocatable * absolute^^^^^is^ not allowed
absolute ^^ * relocatable^^is^ not allowed
absolute ^^ * absolute^^^^^is^ absolute

relocatable / relocatable ^is^ not allowed
relocatable / absolute^^^^^is^ not allowed
absolute ^^ / relocatable^^is^ not allowed
absolute ^^ / absolute^^^^^is^ absolute
.SP;IN +0
Note that "constants" are always absolute, and that byte expressions
must always be absolute.

The "absolute - relocatable" rule above can give rise to a problem
which the Assembler does not detect.  If you coded a statement like:
.SP;IN +15
DATA^^-X
.SP;IN +0
where X is relocatable, the result (i.e. 0-X) will not be as
expected.  When assembled, the negative value of X will be assembled
into the data word, but when the code is loaded, since the value is
relocatable, it will be relocated by the loader.  That is, the data
value will be:
.SP;IN +15
-X + Relocation factor
.SP;IN +0
which is &not the negative of the address of X.

@Constants

The Assembler allows three types of constants.  Decimal integers are
written in the usual form.   Hexadecimal numbers are identified by a
leading ">" followed by hex digits 0-9 and A-F.  Character constants
are identified by enclosing the characters in single quotes "'".  The
character "'" in a character constant is represented by two single
quote marks.  Note that character constants can be used in
expressions as numbers.  The following DATA statements demonstrate
the various types of constants.
.SP;IN +11
DATA^^10^^^^^^^^^^DECIMAL 10
DATA^^10*2 ^^^^^^^DECIMAL 20
DATA^^>F^^^^^^^^^^HEXADECIMAL (DECIMAL VALUE 15)
DATA^^>000F^^^^^^^SAME AS ABOVE
DATA^^'A'^^^^^^^^^CHARACTER (DECIMAL VALUE 65)
DATA^^'A'+1^^^^^^^CHAR (DECIMAL VALUE 65+1=66)
.IN +0;SP
Note that character constants are not the same as strings which are
defined later.

@Definition^of^Terms

The following terms are used in the descriptions of the Assembler
statements in later sections of this manual.

&VALUE - means a data value or an expression which evaluates to a
data value.  The value may be absolute or relocatable.

&LABEL - is an ordinary symbol in the label field of a statement.
Labels begin in position one of the statement.

&NAME - is an ordinary symbol used in an operand field.

&DESTINATION - is the result field.
For example in A=B, A is the
destination.  Allowable ways of coding
the destination operand is specified in
the description of the statement.

&SOURCE - is the source field.  For
example in A=B, B is the source field.
Allowable ways of coding the source
operand is specified in the description
of the statement.

&GENERAL^ADDRESS - is any one of the
forms of addressing allowed by the CPU.
These are:
.SP;IN +5
@@symbol^^^^^^^^-^Symbolic memory direct
@@symbol(Rn)^^^ - Indexed symbolic memory
Rn^^^^^^^^^^^^^-^Register direct
*Rn^^^^^^^^^^^^- Register indirect
*Rn+^^^^^^^^^^^- Register indirect with
auto-increment
.IN +0;SP
&COUNT - is an absolute value such as
the count of the number of bit
positions to be shifted.  The range of
valid count values is specified in the
description of the statement.

&DISPLACEMENT - is an absolute value
such as the displacement of a CRU bit
address from the base CRU address.  The
range of valid displacement values is
specified in the description of the
statement.

&STRING - is a string of characters.
Strings can be coded in one of three
ways.  First, the characters can be
enclosed in single quotation marks (a
single quote within the string is
represented by two single quotes).
Second, the characters can be enclose
in double quote marks (a double quote
within the string is represented by two
double quotes).  Third, by a sequence
of hexadecimal digits preceded by the
hex indicator, ">".  The following
three strings are all identical:
.SP;IN +10
'ASDF'
"ASDF"
>41534446
.IN +0
.IF DSK1.ASMAREF1
.IF DSK1.ASMAREF2
.IF DSK1.ASMAREF3
.IF DSK1.ASMAREF4
€†€Ў†‹•Ÿееееееееее分