textfiles/apple/DOCUMENTATION/lisa

1168 lines
49 KiB
Plaintext
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

______________________________________________________________________________
LISA816 v4.0g SHAREWARE version
by
Randall Hyde
and
Brian Fitzgerald
(c) 1980-1987 Randall Hyde and HAL LABS
all rights reserved.
Note: this shareware version of LISA may be freely distributed, provided that
the following files are included:
LISA816 shareware assembler
ANIX.SYSTEM ANIX system (LISA runs under the ANIX shell)
LISA.DOC this document file
DISASM816.SRC source to the disassembler
SIMPLECDA.SRC source to the simple CDA
After a two-week review period, you are required to either destroy any copies
you have (should you decide NOT to purchase the assembler package) or send
$50.00 (plus $5.00 shipping and handling) to
HAL Labs
18942 Dallas
Perris, CA 92370
APDA should also be carrying LISA816 in the near future, along with the ANIX
package (manual, extrinsic source and ANIX shell source).
The disassembler provided in this package is also SHAREWARE; if you purchase
LISA816, the disassembler is included. If you wish to use the disassembler
otherwise, send $15.00 to the above address (which entitles you to a disk, one
update, and printed documentation).
ANIX is freeware, but is (c) 1982-1987 Randall Hyde.
DISASM816 is (c) 1987 HAL Labs
______________________________________________________________________________
What follows are some notes on using the LISA816 assembler. Providing an
assembler as share-ware is a large task- an assembler is usually not the
intuitive kind of program that a word processor or terminal emulator is. So,
even though the accompanying document is 40K long (longer than the assembler!),
everything is not covered.
Of course not! After all, we want you to buy the assembler. However, we also
want you to get a good feel for what LISA's like. Therefore, there are several
programs included in the package. First, there's the source to a 65816
disassembler. Second, there's the source to a SIMPLE CDA. Each file can be
LOaded into the assembler, ASMbled (to a file on disk) and run.
Any simple questions may be sent online to
GEnie: HAL.LABS
DELPHI: HALLABS
CompuServe: 72250,3226
Until you buy the assembler, we won't answer more than a few simple questions,
of course. Registers users, of course, get better support.
How to set up LISA816:
LISA816 runs under the ANIX shell. Therefore, you must have ANIX running
before you can use LISA816. Either
1) run ANIX.SYSTEM from basic (ie "-ANIX.SYSTEM")
2) make a boot disk with PRODOS and ANIX.SYSTEM
Then, after you have run ANIX, from the ANIX command line, type
LISA816
(assuming that the LISA816 file is in the currently prefixed directory).
ANIX is a command-line interface with many useful programmer extensions;
that's why LISA816 uses it (ANIX was actually developed mainly so that
there would be a decent environment to run LISA in).
After that, you're up and running. We hope.
Have fun!
______________________________________________________________________________
Source Editing Commands
LISA has a few special characters of it's own, that only have meaning in
the insert mode. These special characters are used to enhance source-file
editing.
<<return>> is used to exit insert mode. This command, as do all the
following commands, needs to be used as the first character of an insert
line.
<<control-A>> has the effect of moving the insertion point to before the line
immediately preceding the current insertion point. The previous line is
displayed (for user convenience), and the new line number displayed for
insertion.
<<control-B>> has the effect of moving the insertion point to after the line
immediately following the current insertion point. The next line is displayed
(for user convenience), and the new line number displayed for insertion. If
the insertion point is line N, then line N+1 becomes line N, and the new
insertion point is line N+1.
<<control-W>> has the effect of deleting the line previous to the insertion
point, and then starting insertion at that point. The deleted line is
displayed (for user convenience), and the new line number displayed for
insertion. This is the most useful of the four special editing commands.
Typically, a line will be entered, the user will press return, and then notice
an error. Using <<control-W>> has the same effect as:
<<return>>
M nn
...
<<control-C>> has the effect of deleting the next line in the source following
the insertion point, and placing the insertion point following that line.
The deleted line is displayed (for user convenience), and the new line number
displayed for insertion. If the insertion point is line N, then line N+1 is
deleted, and the new insertion point is line N (because line N+1 was deleted).
Importing and Exporting Text Files
LISA source files are stored in a compressed, tokenized form. This has
several advantages:
* files are smaller
* assemblies are faster
* most errors are caught at edit time, not assembly time
The disadvantage, of course, is that files are not stored in a pure text
format. It is, however, easy to import text from a text file, or to save a
LISA file out as text, by using the READ and WRITE commands. To import text,
simply use a command of the form
READ nnn <textfile
where nnn is the line to start insertion, and textfile is the name of the text
file to read from. LISA will convert each line from the text file into it's
tokenized format. If an error is detected in a line, LISA will stop
momentarily and ask you to fix it - note that you can abort the read-in
process (if, for example, you weren't reading a program text file) by pressing
<<return>> by itself to exit insert mode.
Exporting to a text file is just as easy, using a command of the form
WRITE n1,n2 >textfile
where n1..n2 is the range of lines to write to the text file named textfile.
Normally, LISA writes text files with no space padding to line columns up.
If you want the space padding, insert the TAB switch in the write command:
WRITE -t n1,n2 >textfile
and spaces will be added to pad the columns out as they would be if a LIST
command were issued.
READ and WRITE can also be used to move portions of code from one LISA file
to another. If you have libraries that you raid routines from, or perhaps
equate files that you only want certain lines from, you would use WRITE to
extract the lines needed, and READ to insert them into the correct source file.
LISA editor commands
Note: each command may be abbreviated to the characters shown in upper case.
Optional parameters are enclosed in braces, as {optionalparms}; required
parameters are encased in double-brackets as, <<requiredparms>>.
<<ctrl-D>> (execute ANIX command)
Parameters: output file/device.
Usage: <<ctrl-D>> <<anix command>>
Executes the command following the <<ctrl-D>> as an ANIX intrinsic command.
ANIX will report any errors that occur in the execution of the command.
<<ctrl-P>> (toggle printer on/off)
Parameters: none
Toggles the setting of the ANIX printer device; if printer was off, printer
is turned on, and vice versa. This action is the same as in the ANIX shell.
- (list previous 20 lines)
Parameters: none.
Lists the 20 lines previous to the last line listed (by any list command).
, (list next 20 lines)
Parameters: none.
Lists the 20 lines after the last line listed (by any list command).
. (list 20 lines around current line)
Parameters: none.
Lists the 20 lines around to the last line listed (by any list command);
ie, from -10 to +9 around the current line.
? (command help)
Parameters: output file/device.
Usage: ? {>outfile}
Prints a short summary of all the LISA commands available; if {>outfile}
is present, output is redirected to the selected file or device.
Assemble (assemble source)
Parameters: output file/device.
Usage: Assemble {>outfile}
Assemble the source file in memory; if the optional parameter {>outfile} is
present, output is directed to the selected file or device. If the source
file in memory ends with a CHN " <<file>>" and not an END, the file in memory
is saved out to disk as "T.." and then assembly continues with <<file>>.
BReak (break to monitor)
Parameters: none.
Exits from LISA into the LISA monitor. To return to LISA, use <<control-C>>
for a LISA warmstart (leaves file intact) or <<control-B>> for a LISA
coldstart (does a NEW on re-entry to LISA).
COpy (copy source lines)
Parameters: start line, end line, dest line.
Usage: COpy <<startline>>, <<endline>>, <<destline>>
Copies source lines in the range <<startline>>.. <<endline>> to a position
in the file starting at <<startline>>. Note that <<endline>> must not be
less than <<startline>> and <<destline>> cannot lie within the selected
range <<startline>>.. <<endline>>.
CPu (set CPU type)
Parameters: CPU type
Usage: CPu <<cputype>>
Set CPU type to be of type <<cputype>>. CPU Type must be one of the three:
6502 65C02 65816
If <<cputype>> is omitted, the current CPU type is displayed.
Delete (delete source lines)
Parameters: delete line 1, delete line 2.
Usage: Delete <<delline1>>, {delline2}
Deletes source lines in the range <<delline1>>.. <<delline2>>. If
<<delline2>> is not specified, only line <<delline1>> is deleted. The
range must be legal - <<delline2>> must not be less than <<delline1>>.
DS (dump symbol table)
Parameters: optional file/device.
Usage: DS {>outfile}
Will print the symbol table from the last assembly to the standard output
device. As usual, output may be directed to any ANIX device (>.P for printer,
>filename for file, etc).
Find (find search string)
Parameters: search string.
Usage: Find {searchstring}
Looks for {searchstring} in the file and displays all lines it is contained
in. FIND may be aborted by pressing <<control-C>>. If no search string is
specified, FIND will do nothing.
FReplace (find and replace)
Parameters: search string, replacement string.
Usage: FR {searchstring} ^ {replacestring}
Looks for {searchstring} in the file and replaces it with {replacestring}
where-ever found. FR will prompt for replacement at each occurence of
{searchstring}. FR may be aborted by pressing <<control-C>>. If no search
string is specified, FR will do nothing. If no replacement string is
specified, FR will delete the search string if allowed.
Insert (insert source lines)
Parameters: insert line.
Usage: Insert {insline}
Starts insertion of source code lines at <<insline>>. If <<insline>>
is not specified, insertion starts at the end of the file. Insert mode
is exited by entering <<return>> on a blank line.
LEngth (source file stats)
Parameters: optional file/device.
Usage: LEngth {>outfile}
Will print the statistics for the current source file in memory- length,
number of symbols.
List (List source lines)
Parameters: list line 1, list line two, output file/device.
Usage: List {line1},{line2},{>outfile}
Lists source lines in the range <<line1>>.. <<line2>>. If no lines are
specified, then the entire source file is listed, starting at line 1. If
only the first line is specified, then only that line is listed. If one
line number is given, followed by a comma, then 20 lines are listed starting
at that line. If one line number is given, followed by two commas, then the
entire source file is listed, starting at that number. If both numbers are
given, then the source lines in that range are listed. If the optional
parameter {>outfile} is used, output is re-directed to the selected file
or device.
LOad (load source file)
Parameters: ProDOS pathname.
Usage: LOad <<pathname>>
Used to load a LISA source file from disk. Errors- applicable ProDOS errors,
memory full, not LISA vx.x file.
Modify (modify source lines)
Parameters: modify line 1, modify line 2.
Usage: Modify <<modline1>>, {modline2}
Deletes source lines in the range <<delline1>>.. <<delline2>>, and then
starts insertion at <<delline1>>. Note that MODIFY is equivalent to
DELETE followed by INSERT at the first line <<modline1>>. MODIFY follows
the same syntactic rules as DELETE.
New (clear LISA workspace)
Parameters: none
clears the LISA workspace area in preparation for new source file creation.
Read (read text file source)
Parameters: insert line, read source.
Usage: Read {linenum},{<file}
Inserts lines from the specified text file starting at line linenum; if
linenum is not specified, then insertion starts at the end of the source
file. Insertion ends when end-of-file is reached.
SAve (save source file)
Parameters: ProDOS pathname.
Usage: SAve <<pathname>>
Used to load a LISA source file from disk. Errors- applicable ProDOS errors.
SYstem (system call)
Parameters: none.
Returns control to ANIX shell. To return to LISA, type RUN 303 from ANIX.
TAbs (set tab stops)
Parameters: opcode tab, address tab, comment tab.
Usage: TAbs { <<optab>>, { <<adtab>>, <<comtab>>} }
If no tab stops are specified, then the default tab stops of 10,19,40 are
used. If TA 0 is used, the current tab stops are displayed. If three
tab stops are specified - TA x,y,z - then the opcode field tab is set to x,
the address field tab is set to y, and the comment field tab is set to z.
These tab stops settings are saved with the file. Note that LISA tab stops
are implicit, and used for output formatting - the TAB key is not used on
input.
TRansfer (move source lines)
Parameters: start line, end line, dest line
Usage: TRansfer <<startline>>, <<endline>>, <<destline>>
Moves source lines in the range <<startline>>.. <<endline>> to a position
in the file starting at <<startline>>. TRANSFER is subject to the same
restrictions as COPY; it is the same as COPY, except that it deletes the
original lines from the file.
Write (write source lines)
Parameters: write line 1, write line two, output file/device.
Usage: Write {line1},{line2},{>outfile}
Write out source lines in the range <<line1>>.. <<line2>>. No line numbers
are printed for the listed source lines (as opposed to LIST, which numbers
each line). If no lines are specified, then the entire source file is
listed, starting at line 1. If only the first line is specified, then only
that line is listed. If one line number is given, followed by a comma,
then 20 lines are listed starting at that line. If one line number is given,
followed by two commas, then the entire source file is listed, starting at
that number. If both numbers are given, then the source lines in that range
are listed. If the optional parameter {>outfile} is used, output is
re-directed to the selected file or device. Note that this is the typical
use of write.
______________________________________________________________________________
LISA expression syntax
13.1 Definitions.
A token is the smallest meaningful unit of text in a LISA source line. The
tokens of LISA are classified into special-symbols, identifiers, numbers,
character-strings, and comments.
A LISA source line is composed of tokens, separated by blanks (a blank is
defined as the ASCII space character). The tokens are classified by type
according to the field they are in- label field, opcode field, operand field,
and comment field. Two adjacent tokens must be separated by one or more
separators if each token is an identifier, number, or opcode. Only 1 token
may be in the label, opcode, and comment fields apiece- the operand field can
(and often does) contain multiple tokens.
13.1.1 Character Set and Special Symbols.
The letters are the English characters A through Z, and a through z.
The decimal digits are the numerals 0 through 9.
The hex digits are the numerals 0 through 9, letters A through Z, and a
through z.
The binary digits are the numerals 0 and 1.
The special-symbols are tokens having one or more fixed meanings. The
following single characters are special-symbols:
+ - * / = < > @ # $ % ^ & | \ ( ) [ ] , ' " ~ :
The following character-pairs are special-symbols:
<= >= <> :A :L
13.1.2 Labels.
A label is an identifier appearing in the label field or the operand field
(regular and numeric), or in the opcode field (macros only). A label serves
to denote a constant, variable, program address, data address, or macro call.
Identifiers can be any length up to 63 characters, all of which are
significant. Case is not important in identifiers. Labels can have the
same spelling as an opcode, because type is determined by context. A label
must begin with either a letter (regular labels), the special character {^}
(numeric local labels), or the special character {_} (macro call). Regular
labels can contain letters, numbers, and the special characters {.} and {_}.
A regular label in the operand field can be followed by the type-coercion
tokens {:A} or {:L}.
Numeric local labels are {^} followed by 1 numeric digit, and are referred to
as {^0}..{^9} in the label field, or {<0}..{<9} and {>0}..{>9} in the operand
field. Regular labels must be unique (within their scope); numeric local
labels do not have to be.
13.1.3 Opcodes.
An opcode is an indentifier appearing in the opcode field. An opcode may be
classified into one of three groups- instruction, pseudo-op, or a macro. The
following opcodes are the legal instructions and psuedo-ops for the assembler:
= .DA .DB .EL .FI .GO .IF .LA .LX .MD .ME .SA .SX .TF .WE ADC ADD ADR AND
ANX ASL BBY BCC BCS BEQ BFL BIT BGE BLT BMI BNE BPL BRA BRK BRL BTR BVC BVS
BYT CHN CLC CLD CLI CLV CMP CND CON COP CPU CPX CPY CSP DBY DCI DEC DEX DEY
DFS DPH END EOR EPZ EQL EQU EXP FZR GEN HBY HEX ICL IF1 IF2 INC INP INX INY
JML JMP JSL JSR LCL LDA LDX LDY LIB LNK LSR LST MSG MVN MVP NLC NLS NOG NOP
NOX OBJ ORA ORG PAG PAU PEA PEI PER PHA PHB PHD PHK PHP PHS PHX PHY PLA PLB
PLD PLP PLX PLY PSM REP RLB RLS ROL ROR RTI RTL RTS RVS SAV SBC SBT SEC SED
SEG SEI SEP SET STP STR STX STY STZ SUB SWA TAD TAS TAX TAY TCD TCS TDA TDC
TRB TSA TSB TSC TSX TTL TXA TXS TXY TYA TYX USR WAI WHL XBA XCE XOR ZRO
Any other identifier appearing in the opcode field is assumed to be a macro-
all macros must begin with the macro lead-in character {_}. Any token
appearing in the opcode field that does not parse to an instruction,
pseudo-op, or macro is declared illegal by the editor.
13.1.4 Operands.
The operand field contains one or more expressions; each expression is
separated by the special symbol {,}. An expression consists of a term, which
is an label, number, character-string, or special operand, followed optionally
by operator-term pairs. An operator is a special-symbol. The whole
expression may be prefixed by one or more prefix operators {@}, {~} and {-}.
Byte selector operators {#} (low byte), {/} (middle byte), and {^} (high byte)
may also prefix the whole expression (before the normal prefix operators).
Word selector operators {|}-low word and {\}-high word may also prefix the
expression. Type-coercion suffixes {:A} and {:L} must follow the label they
apply to, not the expression as a whole.
13.1.4.1 Expression modifiers.
Expression modifiers are used to modify an entire expression, and are always
the first prefix to an expression. There are five expression modifiers:
# select low byte (LISA mode) or low word (APW mode 16-bit)
/ select middle byte
^ select high byte (LISA mode) or high word (APW mode 16-bit)
| select low word (LISA mode)
\ select high word (LISA mode)
When used with a 65816 instruction, all the expression prefixes indicate
immediate addressing mode. When used with LISA pseudo-ops, the expression
prefixes select various parts of a 24-bit value for code generation.
13.1.4.2 Operators.
Operators are either monadic (operator preceding expression) or dyadic
(operator infix between two terms.
A monadic operator is one of the following special-symbols.
- @ ~
A dyadic operator is one of the following special-symbols.
+ - * / < > = <= >= <> & | ^ %
13.1.4.3 Labels.
An label appearing in the operand field has the same format as one appearing
in the label field, except for the special case of numeric local labels.
A numeric local label reference in the operand field has the form {<0} to
{<9} and {>0} to {>9}, where {<} and {>} indicate the direction relative to
the expression of the particular local label.
A label in the operand field may have a type-coercion suffix that is used to
force address mode type regardless of the declared type of the label- {:A}
is used to force the absolute attribute for a label, and {:L} is used to
force the long attribute for a label.
13.1.4.4 Numbers.
A number can be either decimal, hexadecimal, or binary. Decimal numbers use
no prefix. Hexadecimal numbers use the {$} character as a prefix. Binary
numbers use the {%} character as a prefix.
13.1.4.5 Character Strings.
A character-string is a sequence of characters delimited by the special
string delimiter characters {'} or {"}. If {'} are used, the high-order
bit of each byte is set to 0; if {"} are used, the high-order bit of each
byte is set to 1. Inside the delimiters, a doubled occurrence of the
delimiter inserts one char of that delimiter in the string without terminating
the character string.
13.1.4.5 Special Operand.
A special-operand is a sequence of one or more characters representing a
certain value. There are several special operand types. The current
program-counter value (of the assembler) can be referenced by {*}.
Macro parameters can be referenced (inside a macro) by {?0}..{?9}. Parameters
to a macro are numbered by occurrence; parameters, where required, may not be
omitted.
13.1.5 Comments.
A comment begins with the {;} character, and optionally (first column only)
with the {*} character. The comment field is the last field in the source
line, and is terminated by a <<return>> character.
13.2 Source Line Formats.
Each source line is separated into 4 fields: label, opcode, operand, and
comment. All four fields do not have to be present on a line, but there are
some restrictions to field appearance. The general case of a LISA source line
is-
line # label opcode operand comment
11 PROGRAM lda SEQUENCE:L + R.OFFST ;get record byte from sequence
The assembler supplies all line numbers. PROGRAM is in the label field
(the first field), so it is parsed as a label. LDA is in the opcode field
(the second field), so it is parsed as an opcode, and recognized as a 65816
mnemonic. SEQUENCE:L+R.OFFST is in the operand field (the third field),
so it is parsed as an operand, in this case as an address expression. The
remainder of the line starts with the character {;}, so it is parsed as a
comment.
If a colon {:} follows the token in the label field, then the line is assumed
to have only the label field in it.
29 STUB:
If the first character of the line is a comment char {;} or optionally {*},
the line is assumed to have only the comment field in it.
241 ; The next routine is responsible for gathering characters one at
If the first character of the line is a blank (space character), then the
label field is assumed to be null, not specified.
122 mvp L.BANK,R.BANK ;move var set
If the line ends after the opcode field, or a comment character is found
following the opcode field, then the operand field is assumed to be null,
not specifed.
45 asl ;shift twice for x4 indexing
46 asl
Note that in each of the above cases, the lines were listed as LISA would
list them, not as they might be entered. LISA tokenizes and formats all
source lines according to it's model, checking syntax at line entry time.
A line entered in as:
122 draw lda #myset ;get set number for DRAW
would be parsed and listed as
122 draw lda #MYSET ;get set number for DRAW
and
123 jsr newplot ;call version 2 plot routine
(with a leading space) would be parsed and listed as
123 jsr newplot ;call version 2 plot routine
13.3 Syntax checking.
Each line is checked for syntax errors on entry. The line is broken up into
tokens, and each token analyzed according to it's field position.
13.3.1 Label field.
There are two types of labels. Alpha labels must start with an alphabetic
character, (upper/lower case), and contain only {A}..{Z}, {a}..{z}, {0}..{9},
{.} and {_}. Labels have a maximum length of 63 characters. Alphabetic case
is maintained as entered, but has no significance on assembly ("Label" is the
same as "LABEL"). Labels start in the first column of a source line. Errors
generated by a bad label include:
Bad character in symbol
Illegal label
Label required here
Numeric local labels start with a caret {^} and are followed by a numeric
digit {0}..{9}. Only 1 digit is permitted after the {^} symbol.
A space { } or a colon {:} must terminate entries in the label field.
13.3.2 Opcode field.
There are two types of mnemonics that are legal in the opcode field. The
first type are the 65816 opcode mnemonics and LISA pseudo-ops. The second
type are macro invocations. All legal 65816 opcodes and LISA pseudo-ops are
listed in section 13.1.3. Macros are identified by a special lead-in
character, currently defined as {_}. Examples:
23 jsr PRINT
24 byt "Enter file name",0
25 _GETNAME
where line 23 contains a 65816 mnemonic {jsr}, line 24 contains a LISA
pseudo-op {byt}, and line 25 contains a macro call {_GETNAME}.
Errors pertaining to the opcode field include:
Illegal mnemonic
Illegal label
13.3.3 Operand field.
The operand field contains 1 or more expressions; the expression type depends
on the mnemonic in the opcode field. Expressions can be:
address expressions
string expressions
If the mnemonic is a 65816 opcode, the expression is embedded in address type
selectors, to indicate addressing modes. Legal 65816 address expressions are:
1 iny ;implied
2 asl ;implied (accumulator)
3 ldx #dexpr ;immediate (8 bit)
4 ldy |aexpr ;immediate (16 bit)
5 asl dexpr ;direct page
6 inc aexpr ;absolute
7 and lexpr ;absolute long
8 ldy dexpr,X ;direct page indexed,X
9 dec aexpr,X ;absolute indexed,X
10 ora lexpr,X ;absolute long indexed,X
11 ldx dexpr,Y ;direct page indexed,Y
12 ora aexpr,Y ;absolute indexed,Y
13 sbc (dexpr) ;direct page indirect
14 jmp (aexpr) ;absolute indirect
15 adc (dexpr,X) ;direct page indexed indirect
16 jsr (aexpr,X) ;absolute indexed indirect
17 cmp (dexpr),Y ;direct page indirect indexed
18 eor [dexpr] ;direct page indirect long
19 jsl [aexpr] ;absolute indirect long
20 sbc [dexpr],Y ;DP indirect long indexed
21 and dexpr,S ;stack relative
22 sta (dexpr,S),Y ;stack relative indirect index
23 mvn bexpr,bexpr ;block move
24 bcs rexpr ;program counter relative
25 brl rlexpr ;program counter relative long
where epxr can be any legal expression that evaluates to an address. Dexpr
must evaluate to a 8-bit (direct page) address. Aexpr must evaluate to a
16-bit (absolute) address. Lexpr must evaluate to a 24-bit long address.
Bexpr evaluates to a 8-bit bank number. In each case, unique special-symbols
provide address type information; the individual addressing types cause unique
opcodes for each instruction to be assembled.
If the mnemonic is a LISA pseudo-op, various combinations of address and/or
string expressions are permitted. Each expression is separated by a {,}
delimiter.
26 adr aexpr,aexpr,aexpr ;16-bit addresses
27 byt "string",expr,'string' ;byte data declaration.
28 .da aexpr,#aexpr,/aexp,\aexpr ;address and byte data
Address expressions consist of identifiers and constants combined with
operators. An expression is of the form
{modifier} {prefix} term {operator-term} {operator-term} . . .
There are 5 expression modifiers:
# use low byte (LISA mode) or low byte/word (APW mode) of expression
/ use mid byte (LISA mode) of expression
^ use high byte (LISA mode) or high byte/word (APW mode) of expression
| use low word of expression
\ use high word of expression
There are 3 prefix operators.
@expr at-operator. evaluates to {PC-expr}, where PC is the value of
the assembler program counter at the start of the
instruction line
-expr negate-operator. evaluates to {0-expr}
~expr not-operator. evaluates to {$FFFFFF EOR expr}.
There are 10 types of terms.
identifier statement label or equate label (from EPZ, EQU, EQL etc).
The value of the label is used.
354 decimal number (no prefix character).
$3B hexadecimal number.
%10011 binary number.
* value of PC counter (of assembler)
?0..?9 macro parameter value (only inside macro). select one of
the 10 possible macro parameters passed to macro invocation.
?# number of macro parameters passed.
?:expr evaluate expr; result must be 0..9 and is used to select
one of the 10 possible macro parameters.
>0..>9 local label reference in forward direction. >0 refers
to next ^0 local label in forward direction, etc. The
value of the local label is used.
<0..<9 local label reference in backward direction. <0 refers
to next ^0 local label in backward direction, etc. The
value of the local label is used.
There are 14 infix operators
+ addition
- subtraction
* multiplication
/ division
% modulo
& bitwise AND
| bitwise OR
^ bitwise EOR
= logical EQUALS
< logical LESS THAN
> logical GREATER THAN
<= logical LESS THAN OR EQUAL
>= logical GREATER THAN OR EQUAL
<> logical NOT EQUAL
String expressions consist of a string delimiter {'} or {"}, followed by some
ASCII characters, and ending with the same string delimiter {'} or {"}. The
{'} string delimiter sets bit 7 (the MSB) of each byte to 0; the {"} string
delimiter sets bit 7 of each byte to 1. To imbed the delimiter char inside
a string, double it.
'A string with bit 7 clear'
"another with bit 7 set"
'one with ''an apostrophe'' inside it'
"a last ""quote"" to remember"
______________________________________________________________________________
Using the LISA calculator
Built in to the LISA assembler is a programmer's calculator that will do
decimal and hexadecimal math to 224-1 (3 hexadecimal bytes, the range of
addresses in the 65816); basic 4-functions (+ - * /), boolean operations
(AND OR NOT), negation, left and right shifts, hex to decimal and vice versa.
It also has help screens for ASCII characters, ProDOS 8/ProDOS 16 equates,
and ANIX and CHARIO equates (for programmers writing programs to run under
the ANIX shell.
To access the calculator, press <<esc>> <<esc>> at any place where LISA is
waiting for a line of input (even in the middle of entering a line of text).
That is, press the ESC key, and then press it again. NOTE: there is a
reason why you must push ESC twice to get into the calculator. Pressing
ESC in ANIX tells it to return the next keypress unchanged; this is the only
way to return all control characters (except RETURN and CTRL-@), since the
normal response to some control characters is as screen editing functions.
So, pressing ESC twice has the effect of returning one ESC char (which is
ASCII $1B or $9B) to the LISA input routine. Once in the calculator, the
line editing characters are not needed, so only one ESC is necessary until
you return to LISA.
The calculator screen should pop up, overlaid on your screen. Don't worry;
since it's a pop-up window, it will restore the screen when you exit.
The calculator looks like this:
_____________ !
| _________ | ESC: quit !
| | | | T: ASCII codes !
| | 0 | | Q: ANIX equates !
| |_________| | P: PRODOS equates !
| | O: CHARIO opcodes !
| < > H M S | !
| & | ^ ~ | H: HEX mode !
| + | M: DECIMAL mode !
| C D E F - | L: clear calculator !
| 8 9 A B * | S: change sign !
| 4 5 6 7 / | &: AND ^: EOR !
| 0 1 2 3 % | |: OR ~: NOT !
| = | <: left shift !
|_____________| >: right shift !
--------------------------------------
Pressing ESC when the calculator is showing will return you back to what you
were doing before you entered the calculator. So, you could be in the middle
of entering a source line and want to calculate a constant before entry.
Pressing ESC twice gets you into the calculator, you do the calculation,
note the result, press ESC again to return to line entry, and enter in the
calculated constant.
The calculator is fairly self-explanatory. It is a regular infix calculator
(TI style rather than HP style); so you enter number then operator then
number, etc. The RETURN key doubles as the "=" key, for ease of use (most
people are well accustomed to hitting RETURN after data entry, much more
so than "="). Also, once you've hit return, all is not lost. You can keep
on with operator and number pairs after that.
The calculator will also retain the value in the display between calls to it.
However, if you do an assembly, the accumulator number will be lost. HEX,
DECIMAL, SIGN, and NOT operations are instantaneous; they affect the
accumulator value only, and do not upset pending calculations.
In the upper right-hand corner of the calculator are some prompts for some
important help screens. First of all is the ubiquitous ASCII chart. This
comes in handy every once in a while (although LISA does handle character
constants well, it helps to know what the actual values are if you're doing
anything the slightest bit tricky or innovative). Just hit a "T", and the
ASCII chart pops up. Press ESC to return back to the main calculator display.
Second, there is a help screen for ANIX equates. Pressing "Q" will bring up
the ANIX equates screen. This comes in handy when you are writing programs
that will execute under the ANIX shell (new extrinsics, little utilities,
etc), and don't want to include the master file of ANIX equates in your small
program. For ANIX v2.1 running LISA816 v4.0, this will be a list of absolute
equates (since this presumes you are running a //e, or IIGS in emulation
mode) for JSR calls; for ANIX v3.0 running LISA816 v5.0, this will be a list
of COP parameter values, since ANIX v3.0 calls are made via the COP
instruction. Once again, pressing ESC will return you to the main calculator
screen.
Third, there is a help screen for ProDOS equates. Pressing "P" will bring
up the ProDOS equates screen. This reference will not only show the ProDOS
call numbers, but also the parameter list structures for each call. Once
again, if you are running ANIX v2.1, this will show ProDOS 8 (which also is
applicable to ProDOS 1.1.1) calls, and their parameter lists; if you are
running ANIX v3.0, this wil show ProDOS 16 calls. The ProDOS equates screen
will show the calls by name; pressing the letter next to the name will bring
up a further screen showing the parameter list required for that call. Press
ESC to exit from an individual parameter list, and ESC from the ProDOS equates
screen to return back to the calculator.
Finally, there is a help screen for the CHARIO calls. Pressing "O" will
bring up the CHARIO equates screen. This will show you the call numbers
for each CHARIO function; the call number is the parameter to CHARIO needed
to invoke that function for the installed console driver. Pressing ESC will
return you to the main calculator screen.
______________________________________________________________________________
LISA pseudo-ops
Note: not all of these pseudo-ops are implemented in the share-ware version
of LISA816 (LISA v4.0g). Specifically:
HEX .DB .LA .LX .SA .SX
LIB PSM LNK RLB ICL
Assembly listing control:
LST turns assembly listing on.
NLS turns assembly listing off.
GEN prints all object bytes for each source line.
NOG prints at most 4 object bytes per source line.
EXP turns assembly listing of macro expansion on.
NOX turns assembly listing of macro expansion off.
CND turns assembly listing of conditionals on.
NLC turns assembly listing of conditionals off.
PAG start new page in assembly listing.
TTL "title" set new title at top of each assembly listing page,
and start new page.
SBT "sub" start new subtitle at top of each assembly listing page
(but does not start new page).
Conditional assembly control:
.IF {expr} assembles code to next .EL or .FI if {expr} evaluates
to TRUE.
IF1 assembles code to next .EL or .FI during pass 1 only.
IF2 assembles code to next .EL or .FI during pass 2 only.
.EL assembles code to next .FI if previous .IF evaluated
to FALSE.
.FI endif clause for the .IF / .EL / .FI construct.
WHL {expr} repeat assembly of code to .WE while {expr} evaluates
to TRUE.
.WE endwhile clause for the WHL / .WE construct.
Macro assembly:
.MD macro starts a macro definition with name macro.
.ME ends macro definition.
Program origin control:
SEG {expr} start new SEGMENT with attributes "expr".
ORG expr defines origin for program code following the ORG.
OBJ expr specifies where the object code is stored in memory.
PHS expr starts in-line assembly of code with new ORG address.
DPH ends in-line assembly and restores to old ORG address.
Labels and equates:
label EPZ expr define "label" as ZERO PAGE label with value "expr".
label EPD expr define label as DIRECT PAGE label (identical to EPZ)
label EQU expr define label as ABSOLUTE label with value "expr".
label EQL expr define label as LONG label with value "expr".
label = expr define label as ABSOLUTE label with value "expr"
(the "=" label is re-definable)
label CON expr define label as CONSTANT label with value "expr".
label SET expr define label as SET label with value "expr".
FZR label define label as ZERO PAGE (needed if label used before
it is defined).
FDR label define label as DIRECT PAGE (identical to EPZ).
FAR label define label as LONG (needed if label used before
definition).
INP label prompt for assembly-time definition of label.
LCL label define label as local to specified section (scope
ends with RLS).
RLS label marks end of local label scope defined with LCL.
Constants and storage:
BYT expr, .. define byte constants of low-order 8 bits of each expr.
HBY expr, .. define byte constants of mid-order 8 bits of each expr.
BBY expr, .. define byte constants of high-order 8 bits of each expr.
.DA expr, .. define byte, word, string constants.
ADR expr, .. define word constants (usually addresses)
low byte, then high byte.
DBY expr, .. define word constants (usually addresses)
high byte, then low byte.
CSP expr, .. is JSR followed by byte, word, strings (same syntax
as .DA)
DFS expr,{e} define space of expr bytes, optionally initialized to e.
HEX hexdigits define hex string of bytes.
LONG expr,.. define long (and byte and word) constants
String declaration:
BYT "string" define string- {'} creates with bit 7=0, {"} creates
with bit 7=1
DCI "string" define string as in BYT; bit 7 of last char is inverted
from normal.
RVS "string" define string as in BYT, but with chars generated in
reverse order.
STR "string" define string as in BYT, with length byte preceding
string (PASCAL)
ZRO "string" define string as in BYT, with $00 terminating string
(C-string)
Control operations:
CPU type set CPU to assemble for. type = {6502, 65C02, 65816}
.DB declare what bank the DBR (data bank register) is
pointing to.
.LA declare 16-bit ACCUMULATOR mode.
.SA declare 8-bit ACCUMULATOR mode.
.LX declare 16-bit INDEX mode.
.SX declare 8-bit INDEX mode.
END end of source.
.TF "file",type declare file to which generated code is saved to,
and type (type is defined in HEX).
SAV "file" saves memory as binary file.
ANX "cmd" send cmd to ANIX shell to be executed as an ANIX
intrinsic.
CHN "file" chain to next file to be assembled.
ICL "file" include source file in assembly.
PSM "file" include packed-sym file in assembly.
LNK "objfile" include object code in link.
LIB "library" extract needed object code from library in assembly.
RLB "objlib" include information from Run-Time-Library in linkage.
.GO expr jumps to address expr to execute a machine language
routine.
USR expr parses expr, and jumps to user command.
MSG "string" print message to stdout during assembly
PAU force assembly error ("PAU encountered")
______________________________________________________________________________
ANIX Commands
The format for these commands is given in parenthesis. Unless otherwise
stated, these commands are to be followed by a carriage return.
INTRINSIC COMMANDS
* (Asterisk) if an asterisk appears in the first
column, that is, the first space, in a line processed by
ANIX, then the rest of the line will be ignored. The use
of this instruction may not be obvious; it is used to
insert comments within an EXEC file.
Brk (BRK) Transfers control to the Apple monitor at
location $FF/FF65. To return to ANIX, type A000G from the
monitor to do an ANIX warmstart.
Catalog (CATALOG {pathname} <<return>>) Displays the listing of
a directory file. Abbreviation: "CAT". The pathname
is optional; if it is present, ANIX will give the specified
directory, and if it is absent, then ANIX will look for
the default directory. The pathname must be of a DIR
(subdirectory) type file, or a disk (a disk is indicated
with ".Dn", where "n" represents a number between 1 and 8).
Close (CLOSE <<return>>) Will close any and all open ProDOS
files. This command may be useful after a program
bombs, in order to make sure all the programs opened by the
program are closed properly, and their buffers are freed by
ProDOS.
Date (DATE <<return>>) This prints the date, in the format
"mm/dd/yy"; it will, that is, if you have a ProDOS
compatible clock installed. (always the case on a IIgs).
Otherwise, this command will print the last date specified
with the SETDATE command; and if the SETDATE command has
not been used, then "-NO DATE" will be printed.
Delete (DELETE <<pathname>> <<return>>) This will erase a file
from a disk; the pathname is not optional for this command. It
will not erase a file if its "D" attribute flag is turned
off (if you don't know what an attribute flag is, wait for
the latter part of this section), so it will have to be
unlocked before it may be deleted.
NOTE: When deleting a subdirectory, it must be empty
before the DELETE command will work on it.
Exec (EXEC <<pathname>> <<return>>) The EXEC command is used to
redirect input from a textfile rather than a keyboard; the
pathname is not optional, and must be the name of a TXT
type file, a sequential text file. When the EXEC command
is executed, ANIX then begins looking for ANIX commands
from the named textfile rather than the keyboard.
Load (LOAD <<pathname>> {hex address} <<return>>) Loads a BIN
or SYS file from disk into memory; a pathname is required,
but the hex address is optional. If the optional hex
address is not present, then the file is loaded at the
location from which it was saved. Example:
LOAD SHORT.PROGRAM
Lock (LOCK {-N -R -W -D} <<pathname>> <<return>>) This command
and the Unlock command are closely associated, and they
share the same syntax. The Lock command will set any or
all of four attribute flags: the N (rename) flag, the R
(read) flag, the W (write) flag, and the D (Delete) flag.
The N (rename) flag, upon being set, will thereafter
prevent the given file from being renamed, until the N
flag for the file is Unlocked. The R (read) flag will
stop anyone from reading a file which isn't meant to be
touched. The W (write) flag will prevent someone actually
saving a new version of a program with the same name of a
version you wish to preserve. Finally, the D (delete)
flag will stop the deletion of a file.
Any of these flags, once locked, may be reset, using the
Unlock command.
Online (ONLINE <<return>>) Lists all the volumes currently on-line
The result will be a line for each volume of this form:
s/d volume-name
In these lines, "s" is the slot number, "d" is the drive
number, and volume-name is the name of the volume in the
specified slot and drive.
Prefix (PREFIX {pathname} <<return>>) The pathname is optional.
See the discussion of pathnames and prefixes following
this listing for an explanation of this command.
Rename (RENAME <<pathname>>, <<pathname>> <<return>>) Changes
the name of a file in a directory. The pathnames are
not optional, and they must be the same, except for the
ending filenames. Examples:
Rename /directoryname1/subdirectoryname2/thisprogram,
/directoryname1/subdirectoryname2/thatprogram.
Rename Yourfile,Myfile
Run (RUN <<hex address>> {parms} <<return>>) Runs (calls) the
assembly language program at the hex address named; the hex
address is required. The optional parameters are for the
use of the assembly language program.
Save (SAVE <<pathname>> <<start addr>> <<length>> <<return>>)
This is for saving out an object file. The hex address and
length must be included.
Syssave (SYSSAVE <<pathname>> <<start addr>> <<length>> <<return>>)
This is the same as the Save command above, except that it
saves a SYS type file rather than a BIN type file.
Time (TIME <<return>>) Prints the time, assuming there is a
ProDOS compatible clock present. If there is no clock,
then this command prints the last time set by the extrinsic
SETTIME command, or 00:00 if SETTIME has never been used.
Unlock See LOCK.