.SP2
\INTRODUCTION


The GPL assembler reads a source
program, written in GPL, and translates
it into an object program for loading
into GRAM.  The source program
statements are read from the "source
file" which may be augmented by one or
more "copy files".  The object program
is written to the "object file".
During assembly, an "object listing
file" can be created which shows the
object code generated along with the
source statements.

The GPL object code, output by the
assembler can be loaded into GRAM using
the GPL Object Loader.  The GPL program
can then be executed using the normal
Operating System facilities (i.e. menus
and BASIC calls).

Note that all GPL code is in absolute
format.  That is, the object code must
be loaded at the addresses specified in
the source program.


\Getting^Started

Before you do anything else, make a
backup and a working copy of the GPL
Assembler distribution disk.  Save the
distribution disk in a safe place.  The
assembler is distributed on one single
sided single density disk.  The disk
contains the following files.

.IN +5
GLOAD^^^^^ -^ GPL Object Code Loader
GPLMAC^^^^ -^ Macro definitions
RAGGASM^^^ -^ The GPL Assembler
(Segment 1)
RAGGASN^^^ -^ The GPL Assembler
(Segment 2)
RAGINSGA^^ -^ Assembler installation program
RAGSAMP/S^ -^ Sample GPL Program
.IN +0;SP
\Assembler^Installation

The GPL assembler, as distributed, is
set up to work with a generic printer
and a standard E/A Option 5 loader such
as the XB LOAD program provided.  The
assembler is, however, designed to work
with various loaders and printers, and
to produce a compact listing to reduce
print time and paper usage.  In order
to make use of its capabilities you
must "install" the Assembler with
options suitable to your environment.
The RAGINSGA (E/A Option 5) program or
the XRAGINSGA (XBASIC) program on the
distribution disk will prompt you for
the values for your environmemt and
then modify the Assembler on disk so
that it will use your values.

In order to produce a compact listing
and still have the listing contain full
information, the printer should be set
up to print in elite mode at 8 lines
per inch.  Most printers can do this
although it is not required.  To
accomplish this printing, the assembler
will send a "setup sequence" of control
characters to the printer before
printing the first line of the listing,
and will send a "reset sequence" of
control characters to the printer after
printing the last line of the listing.
The assembler will also provide a left
margin, will truncate any lines that
are too long for the printer and will
count the number of lines per page.
The length of a line and the number of
lines per page must be coordinated with
the way your printer is set up.

During entry of your default values,
press ENTER to proceed to the next
prompt or press BACK (FCTN 8) to begin
again at the beginning.  Typing an
asterisk (*) as the first character of
the line indicates that the
corresponding default value is not to
be changed.  A response of all blanks
or of just pressing ENTER indicates
that there is to be &no default value.
Each of the prompts is described below.

&Installation^Drive^Number

Enter the number of the disk containing
the original Assembler modules.  During
installation the Assembler module,
RAGGASN, is loaded from this drive and
then saved back to the drive.  The
default installation drive is 1 (i.e.
DSK1).

&Screen^Colour

Enter, in hexadecimal, the forground
and background colours for the display.
The distributed colour is >1B.

&Printer^Name

Enter the device/filename for your
printer.  If no printer name is
entered, then the Assembler will prompt
for the printer name each time it is
run.  The printer file may be directed
to disk.

&Printer^Setup^Sequence

Enter the printer control codes
required for making your printer print
the assembler listing in the mode you
want. For example: in elite mode at 8
lines/inch, or in compressed mode at 8
lines/inch.  Enter the data in
hexadecimal (2 digits per byte).  You
will have to refer to your printer
manual to determine the proper codes
for your printer.

&Printer^Reset^Sequence

Enter the printer control codes
required to make your printer revert to
its normal printing mode.  This
sequence should contain a form feed to
position the printer at the top of the
page.  Most printers have a single
"reset" code.  Enter the data in
hexadecimal.  You will have to refer to
your printer manual to determine the
proper codes for your printer.  The
distributed reset seguence is "0C",
which is form feed.

&Lines^Per^Page

Enter, in decimal, the number of lines
to print before a form feed is issued.
The number of lines per page depends
upon your paper size and the printer
setup.  For example, enter 75 for 11"
paper at 8 lines/inch, or 55 for 11"
paper at 6 lines/inch.  You must allow
for the top and bottom margin on the
page.  The distributed value is 55
lines per page.

&Maximum^Line^Length

Enter, in decimal, the maximum number
of characters to be printed per line.
The Assembler can print up to 116
characters on a line.  All lines will
be truncated to the length you specify.
The value specified depends upon the
capability of your printer and on the
way your printer is set up.  Most
printers can print an 80 character line
in standard mode and a 96 character
line in elite mode.  The distributed
value is 80 characters per line.

&Left^Margin

Enter, in decimal, the number of blanks
to be printed at the beginning of each
line to provide a left margin.  The
value must be in the range 0 to 10.
The distributed value is 4.

&Default^Options

Enter up to 6 one letter option codes
that are to be used as the defaults
when no options are entered during an
assembler run.  The distributed default
options are "LS".

&Type^of^Return^(RT^or^BLWP)

The Assembler can exit in two ways.
First, it can return to the loader (or
cartridge) that loaded it.  This is
what is done if "RT" is specified.
This is the normal return for the
Editor/Assembler Cartridge Option 5 and
the TI Writer Cartridge Option 3.
Second, it can execute a "BLWP @@0"
which causes the 4A to reset.  This is
done if "BLWP" is specified.  Some
loaders are not prepared for programs
to return (i.e. a popular RAM DISK
LOADER), the BLWP return will suit
these loaders.  The distributed value
is RT.

\RUNNING^THE^ASSEMBLER

The RAG SOFWARE GPL Assembler is a
standard E/A Option 5 program and is
independent of the module used to run
it.  It has been run using Option 3 of
TI Writer, Option 5 of Editor/Assembler
and Option 1 of GRAM KRACKER.  Once
loaded, the Assembler can process a
batch of source files.  The assembler
is a three pass assembler.  If
possible, pass 2 will be skipped.  A
three pass assembler is necessary for
GPL because the size of the address in
some instructions is dependent upon the
value of the address.


\Assembler^Prompts

The Assembler will prompt you for the
macro definition file name, the source
program file name, the object file
name, the printer file name, the
assembly identification information,
and the options for this assembly.
When an assembley is completed, the
Assembler will ask if you want to
assemble another program.  Note that
all device/file names are specified in
the usual form.
.SP;LM +3;IN -3
MACROS:
.IN +0
Enter the device and file name of your
macro library.  A null entry (i.e. just
press ENTER) indicates that no macro
library file is required for this
assembly.  The file name of the
supplied macro library is RAGMAC.  When
you press ENTER, the Assembler will
read the macro definitions into memory
before continuing with the next prompt.
Once read, the macro file is no longer
required so that your macro library
could be on a separate disk.

An asterisk can be entered as the macro
file name to indicate that the macros
are to be read from RAM in the module
plugged into the console (loaded there
in a previous assembly), or when doing
other than the first of a batch of
assemblies to indicate that the macros
from the previous assembly are to be
used.
.SP;IN -3
SOURCE:
.IN +0
Enter the device and file name of your
assembler source statements.
.SP;IN -3
OBJECT:
.IN +0
Enter the device and file name into
which your object program is to be
written.
.SP;IN -3
PRINTER:
.IN +0
Enter the device and file name for the
assembler listing file.  This prompt
occurs only if there was no default
printer specified when the assember was
installed.
.SP;IN -3
ID/DATE:
.IN +0
Enter up to 9 characters of
identification for this assembly.  The
information entered appears in three
places during the assembly: on the
listing heading line, on the last
record of the object file, and as the
value of the &&S4 system macro symbol.
As the prompt suggests, today's date is
probably the most useful
identification, then both the listing
and the object file will be dated.
.SP;IN -3
OPTIONS:
.IN +0
Enter the one letter option codes.
Except for the "&&" option, the codes
may be entered in any order.  The
option codes are:
.LM +4;IN -4
E^-^produce a listing of source errors.
This option is assumed if any other
listing option is specified.
F^-^show full assembled data in the
listing.  If this option is not
specified then a maximum of 8 bytes of
data is shown on the listing (a single
line).  The full data is, of course,
always assembled into the object file.
G^-^include macro generated statements
in the listing.  The macro generated
statements are identified in the
listing by a plus sign following the
statement number.
L^-^produce a listing of source
statements,
M^-^include macro directives in the
listing. Macro directives are
identified in the listing by a minus
sign preceeding the statement.
S^-^produce a symbol table listing,
X^-^produce a cross-reference listing,
4^-^use the 4K RAM at address >7000 for
storage of macros (i.e. Mini Memory
RAM),
8^-^use the 8K RAM at address >6000 for
storage of macros (i.e. Super Space or
GRAM KRACKER RAM),
&&^-^set the system macro symbol &&S0
to the remainder of the options line.
.LM -4;SP;IN -3
MORE?
.IN +0
If you wish to continue with this batch
of assemblies, enter "Y" and the
Assembler will reinitialize itself and
prompt as above for the next program to
be assembled.  Any other entry will
cause the assembler to terminate.
.LM -3;IN +0;SP
If during prompting you wish to restart
from the beginning, simply press BACK.
Note, however, once the macro file has
been read BACK will only return you to
the "SOURCE" prompt.


\The^Object^File

The object file output by the Assembler
contains identification so that the
source, object and listing can be tied
together.  First, the source file name
is placed on the first object record,
which also contains the IDT directive
information.  Second, the last record
of the object file (the colon record)
contains the Assembler name/version,
and the ID/DATE information that was
entered.

The GPL object file created by the
Assembler is a FIXED 80 file containing
"tagged object" in compressed format.
This tagged object file is idential in
form and content to the tagged object
created by 9900 Assemblers.  The tagged
object contains fields beginning with a
tag followed by data.  The tag
identifies the type of data in the
field.  The first tag in an object
program is ">01", which indicates that
the object code is in compressed
format.

The following table lists the tags used
and gives the content of the data field
that follows the tag.
.BP;LM +8;IN -5
TAG^^^^^^CONTENTS OF DATA FIELD
--------------------------------------------------------
>01^^^^^^2 Bytes, always contains >0000
^^^^^^^^^8 Characters, text from the IDT Directive
^4^^^^^^^2 Bytes, REF chain in absolute code
^^^^^^^^^6 Characters, REF name
^6^^^^^^^2 Bytes, DEF value in absolute code
^^^^^^^^^6 Characters, DEF name
^9^^^^^^^2 Bytes, absolute location counter
^B^^^^^^^2 Bytes, absolute code
^F^^^^^^^No data, end of object record
.LM -8;IN +0;SP
The last record of an object file
begins with a colon.  It contains only
information on the Assembler name,
version and the ID/DATE information.

\Table^Sizes

The Assembler builds several tables
during an assembly.  Each of the tables
is described below.
.SP
The Symbol Table is used to save all
symbols and macro names defined in the
assembly.  Each entry in the table is
12 bytes.  The symbol table is built in
high memory from the end of the
assembler code up to >F600, the maximum
size is approximately 1,100 entries.

The Cross Reference Table is used to
accumulate the refereces to each symbol
in the assembly.  Each entry in the
table is 4 bytes.  The cross reference
table is built in VDP RAM, the maximum
size is approximately >2AD0 bytes
giving a maximum of 2,740 entries.

The Macro Definition Table is used to
save all macro definitions encountered
in the macro file or the source file.
All the lines of the macro definitions
are stored as variable length strings
with the length byte preceeding the
statement.  The macro table is built in
VDP RAM, the maximum size is
approximately >2AD0 bytes providing
enough space to hold the equivalent to
a 40 sector macro file.  The macro file
will be moved to module RAM if the 4 or
8 option is specified, or will be moved
to High Memory after pass 2 if there is
enough space after the symbol table is
built.  If the macro table cannot be
moved to CPU RAM then it must share the
VDP RAM with the cross reference
table, limitimg the size of the cross
reference table.

The OBJREC Directive Table is used to
save the BEFORE text during pass 1 and
to save the AFTER text during pass 3.
Each text entry is stored as a variable
length string with the length byte
preceeding the text.  The table size is
>02FF bytes, providing enough space to
hold about 20 40-byte object records.
.SP2;cp5
\THE^GRAM^LOADER

The object code output by the GPL
Assembler can be loaded into GRAM using
the GPL Object Loader, GLOAD.  The
GLOAD program is a standard E/A Option
5 program that can be loaded by many
loaders.  Once loaded and running, the
only system facility used by GLOAD is
the DSR required to read the object
files.  In particular, GLOAD does not
use the system KSCAN routine, nor any
data or subroutines in GRAM.

The loader prompts you to enter object
file names.  For each object file
loaded, the loader displays the IDT
information and the information from
the "colon" record if any.  The loader
can load either compressed or
uncompressed tagged object code, and
can resolve REFs and DEFs in the loaded
object code.

The loader screen is divided into three
areas.  The top area displays the
loader title and the current GRAM
address where data is being loaded.
The centre area displays user prompts
and messages.  The bottom area shows
the first 22 entries in the REF/DEF
table.  The REF/DEF table can contain
over 700 entries although few programs
will have more than the 22 displayed.
The display shows an "R" for an
unresolved REF and a "D" for a DEF.
The hexadecimal address following the D
is the defined address of the symbol.
The hexadecimal address following the R
is the address where the unresolved
symbol is first referenced.  All
refrences to an unresolved symbol are
chained together, the address displayed
is the first link in the chain.

The loader continues prompting for
object file names until BACK is pressed
(QUIT will of course do its usual
thing), at which time the number of
unresolved references will be displayed
if any and you will be given a chance
to continue loading or to exit using
QUIT.

Note that the GRAM loader only loads
GPL code, it does not begin execution
of it.  When you exit from the loader
you use the normal GROM Operating
System facilities to execute your code,
or you can save the GRAMs to disk using
the save utility provided with your
GRAM device.
.SP2
\MACRO^DEFINITIONS

The macro definitions in file GPLMAC
are described in the sections below.
The examples of usage show the
generated code in the lines prefixed
with a plus sign (just as printed with
the Assembler's G option).

\IF^DIF^-^Test^and^Branch

^^^^^[label]^IF^^^
operand1,condition,operand2,target
^^^^^[label]^DIF^^
operand1,condition,operand2,target

The "operand1" value is compared to the
"operand2" value and if the "condition"
is true a branch is made to "target".
The operand values are bytes for IF and
double bytes for DIF.  The operand1
address may be specified in any of the
"gdest" forms.  The operand2 address
may be specified in any of the "gsrc"
forms (including immediate data).  The
target is specified as for the BR or BS
instruction.  The condition is
specified as:
.sp;in+5
EQ - Logical or Arithmetic, equal
NE - Logical or Arithmetic, not equal
Z^ - Logical or Arithmetic, equal to 0
^^^^^^^^^^^^^^^^(operand2 ignored)
NZ - Logical or Arithmetic, not equal
to 0
^^^^^^^^^^^^^^^^(operand2 ignored)

GE - Arithmetic, greater than or equal
GT - Arithmetic, greater than
LE - Arithmetic, less than or equal
LT - Arithmetic, less than

H^ - Logical, higher than
HE - Logical, higher than or equal
L^ - Logical, lower than
NH - Logical, not higher than
NL - Logical, not lower than
.sp;in+0
Note that the GPL comparision
instructions, CGE, CGT, etc., compare
the destination to the source which is
sort of backwards.  The IF and DIF
macros appear to do the comparision in
the straight forward left to right
manner.  IF and DIF also provide the
reverse conditions so that you do not
have to compare for a condition and
then branch if it is not met.

The IF and DIF macros also check for
the special situation of comparing for
EQ or NE to 0 and use the CZ or DCZ GPL
instructions.

Examples:
.sp;in+5;AI
        IF    @A,EQ,@B,AREEQ
+       CEQ   @B,@A
+       BS    AREEQ
 TESTA  IF    @A,GT,3,GT3
+TESTA  CGT   3,@A
+       BS    GT3
 TEST0  DIF   @A,EQ,0,ISZERO
+TEST0  DCZ   @A
+       BS    ISZERO
.sp2;in+0;fi
\DAT^-^Display^AT
.sp
^^^^^[label]^DAT^^^row,column,text

The DAT macro generates the FMT
suboperands necessary to display the
"text" at the specified "row" and
"column".  If the row or column is
coded with a leading plus sign then it
is taken to be an increment for the
current row or column.

Examples:
.sp;in+5;ai
        FMT
        DAT   3,2,'HI THERE'
+       ROW   3
+       COL   2
+       HTEX  'HI THERE'
 X      DAT   +2,5,>01020304
+X      IROW  +2
+       COL   5
+       HTEX  >01020304
        FEND
.FI;SP2;IN+0
\DEFSW^-^Define^Switches

^^^^^base^^^DEFSW^sw1,sw2,...,sw8

The DEFSW macro defines the names of up
to 8 switches contained in the "base"
byte.  Each switch is a single bit
defined as 1 for ON and 0 for OFF.  The
"base" must be defined at another place
in the source program.  The switch
names, "sw1", "sw2", etc., must be
valid assembler symbols with a maximum
length of 5 characters.  The macro
generates two names for each switch
defined.  The first name is the address
of the switch and is formed by
appending an "S" to the specified name.
The second is the value of the bit with
the switch ON, and is formed by
appending a "V" to the specified name.

Note that all bits within the "base"
byte neen not be defined.  The base
byte may be defined in either CPU or
VDP RAM.

Switches are defined by this macro,
they may be set using the SETSW macro
and tested using the IFSW macro.

Examples:
.sp;in+5;ai
 FLAGS  EQU   >0400       Define flags
 CPUFLG EQU   >8302
*
 FLAGS  DEFSW SW1,SW2,SW3 Define switches
+SW1V   EQU   >80
+SW1S   EQU   FLAGS
+SW2V   EQU   >40
+SW2S   EQU   FLAGS
+SW3V   EQU   >20
+SW3S   EQU   FLAGS
*
 CPUFLG DEFSW FIRST,,THIRD,,FIFTH
+FIRSTV EQU   >80
+FIRSTS EQU   CPUFLG
+THIRDV EQU   >20
+THIRDS EQU   CPUFLG
+FIFTHV EQU   >08
+FIFTHS EQU   CPUFLG
.FI;SP2;IN+0
\SETSW^-^Set^Switch

^^^^^[label]^SETSW^switch,status

The SETSW macro is used to set the
"switch" to the specified "status".
The "switch" name must be defined with
a DEFSW macro.   It may be specified as
either a CPU or VDP RAM direct address.
The "status" is specified as either ON
or OFF.

Examples: Using the switch definitions
from the DEFSW example.
.sp;IN+5;AI
        SETSW V@SW1,ON
+       OR    SW1V,V@SW1S
 SETOFF SETSW @THIRD,OFF
+SETOFF AND   255-THIRDV,@THIRDS
.FI;IN+0;SP2
\IFSW^-^Test^Switch^and^Branch

^^^^^[label] IFSW^^switch,status,target

The "switch" is tested and, if the
"status" matches, a branch to "target"
is taken.  The "switch" is specified as
a CPU or VDP RAM direct reference to a
switch name defined via the DEFSW
macro.  The "status" to be tested is
specified as either ON or OFF.  The
"target" is specified as required by
the BR and BS instructions.

Examples: Using the switch definitions
from the DEFSW example.
.sp;IN+5;AI
        IFSW  V@SW1,ON,ISON
+       CLOG  SW1V,V@SW1S
+       BR    ISON
 TEST   IFSW  @THIRD,OFF,NOT3
+TEST   CLOG  THIRDV,@THIRDS
+       BS    NOT3
.FI;IN+0;SP2
\DIAGNOSING^ASSEMBLER^FAILURES

Every attempt has been made to insure
that the Assembler has no bugs,
however, in every complex program the
possibility of bugs always exists.  In
additon, bugs may also exist in the
operating system facilities used by the
Assembler.  There are three possible
type of failures.
.SP;LM +5;IN -3
1.^The Assembler completes normally,
but some instruction or data was
assembled incorrectly.
2.^The Assembler completed, but the
listing or disk files were incomplete
or in error.
3.^The Assembler did not complete
and/or the system required rebooting.
.LM -5;IN +0;SP
In all three cases, the first thing to
do is to correct all source errors that
were found by the Assembler.  The
Assembler can really only correctly
assemble correct programs, although it
tries to diagnose incorrect statements.
As the old saying goes: "Garbage in
equals Garbage out".

In the first case above, you should be
sure that you understand what should be
assembled.  The language supported is
fully described in "The Graphics
Programming Language" document supplied
with the Assembler.  If macro
definitions which test which pass the
Assembler is in are used, these should
be checked carefully.

In the second and third cases above,
either the Assembler or the operating
system may be suspect.  In these cases,
you should reduce the dependency of the
assembler on the operating system.
This can be done by not using any of
the listing options.

Finally, all bugs discovered as well as
any usability problems should be
reported to:
.SP 2;IN +15
RAG SOFTWARE
R.^A.^Green
1032 Chantenay Dr.
Gloucester, Ont.
CANADA^^^^K1C 2K9
.IN +0;SP
If possible, a disk with the source
program that can not be assembled
should be sent.  This will make finding
the bug easier.  If a disk is sent, the
material on the disk will &only be used
for finding the bug and will be
returned with a corrected version of
the assembler.

\TECHNICAL^MATERIAL

This document and the GRAPHICS
PROGRAMMING LANUGAGE manual fully
describe the language and operation of
the Assembler.  More information on the
hardware and the Operating System of
the TI 99/4A can be obtained in other
publications such as those listed
below.
.SP;LM +3;RM -3;IN -3
1.^TMS 9900 16-Bit Microcomputer
.IN +0
Preliminary Data Manual
Texas Instruments, Inc., 1981
.SP;IN -3
2.^Texas Instruments Home Computer
.IN +0
Editor/Assembler
Texas Instruments, Inc., 1981
.RM +3;LM -3;IN +0