| |
NF Assembler Documentation
Contents
Assembler Documentation
Quick documentation for the NinjaForce Assembler v2.14
------------------------------------------------------
You should be familiar with 65816 assembly language to use this program.
Launch the file NF.AS.ED, which is a complete ProDOS 8 application including an
editor for assembler sources. Read the documentation NF.ED.DOCS for details on
the editor.
Your code has to follow certain standards:
A label, the command, the operand and the comment must be separated by one or
more spaces. Labels must begin in the first column. The command may not begin in
the first column. If you don't have a label in a line, insert at least one
space. It is also possible to type in blank lines (with no spaces inside). This
allows you to better structure your source code.
Example:
label command operand comment
org $300 ;begin of program is $00 0300
sht ;use short registers
begin ldx #0 ;load the x - register with 0
]loop lda text+1,x ;load the accu with a text char
jsr $fded ;print it
inx ;increment x - register
cpx text ;compare x with length byte before ascii text
blt ]loop ;loop until done
rts ;finished
text str "Hi there!" ;length byte, then Ascii text.
The special NF Assembler Commands:
----------------------------------
ORG The operand is the begin of the program (memory location).
= or EQU Defines a label.
DLW Define Long Word(s). Must be separated by commas.
DW Define Word(s). Must be separated by commas.
DFB Define Byte(s). Must be separated by commas.
HEX Define Hex-Byte(s). No $ needed here. Must be separated by commas.
DS Define Storage. Operand-number of zeros (byte values) are written.
If the operand is the backslash character (/), the code is filled
up with zeros to the next page ($xx00).
MSB Operand is either ON or OFF. - Takes effect on ASC and STR commands.
COD Operand (byte value) is used to EOR Ascii Texts so that one can not
read these from the monitor. This is a good method to protect secret
texts from the eyes of others. - Takes effect on ASC and STR commands.
ASC Operand holds text in " "
STR Operand holds text in " ". A length byte is put before the text.
TYP Operand (byte value) specifies the filetype of the outputfile. Look
up the filetypes in a ProDOS reference. ($ff is a P8 - System file).
If you do not use this command, the filetype of the outputfile will be
BIN.
IMP Operand "/disk/file" Loads in a non-forkfile at program counter
location and includes it within the output file.
INS Operand "/disk/source" Loads in another source code file and inserts
its code at program counter location. See below for further notes.
LNK Link. Output will be a GS/OS loadfile. Must be placed before code
starts and replaces the ORG command. (See below.)
SHT Use short (8 Bits) m (akku) and x,y registers.
LNG Use long (16 Bits) m (akku) and x,y registers.
M08 8-Bit m (akku) register.
M16 16-Bit m (akku) register.
X08 8-Bit x,y registers.
X16 16-Bit x,y registers.
MAC Begin macro definition. This command must be headed by the macro name.
(Look at the example later in this text.)
^^^ End macro definition. Important: This is the only command wich may not
have a label in front of it.
LOP Begin of assembler loop. The operand gives the number of cycles to run
through loop. Minimum is 1, max is 0, which is $10000. See source code
example for more information on how to program using loops.
<<< End of loop. See LOP.
LST If this command appears in the source file, you'll get a list output
of all labels, sorted as they were defined.
IMPORTANT: This command has been disabled. Use the debugger instead.
; or * comment lines must begin with one of these characters. You can of
course put comments behind any command line.
Operand formats:
----------------
Decimal 15
Hexadecimal $15
Binary %10010010
Ascii "a" or "ab"
Program Counter *
Label name
Note: If the operand length exceeds the number of bytes needed (e.g.:
lda #$e10203) then the lowest are used (lda #$0203 or lda #$03) if you do not
use < or ^ symbols as shown below: (long = $e10203)
Entered value: Result: (long akku) Result: (short akku)
lda #<long lda #$e102 lda #$02
lda #^long lda #$00e1 lda #$e1
Addressing Modes:
-----------------
inc implied
lda #OP direct
lda DP direct page
lda DP,x direct page indexed with x
lda OP absolute
lda OP,x absolute indexed with x
lda OP,y absolute indexed with y
lda (DP,x) direct indexed indirect
lda (DP),y direct indirect indexed with y
lda DP,s stack relative
lda [DP] direct indirect long
lda LONG absolute long
lda (DP) direct indirect
lda (DP,s),y stack relative indirect indexed with y
lda [DP],y direct indirect long indexed with y
lda LONG,x absolute long indexed with x
jmp (OP,x) absolute indexed indirect
jmp (OP) absolute indirect
bra OP program counter relative
brl OP program counter relative long
Pseudo Commands:
----------------
You may use these: Instead of these:
BLT Branch less than. BCC
BGT Branch greater than. BCS
BGE Branch greater or equal than. BCS
Local labels:
-------------
A local label begins with a ] character (e.g.: ]loop ) and may be defined more
than one time. If used as an operand (e.g.: bra ]loop ) the last defined is
used here. Example:
ldx #0
]loop inx
bne ]loop ;this will branch to the line before
ldy #0
]loop iny
bne ]loop ;this will branch to the previous line, too
Macros:
-------
NF Assembler can handle macros, which must be defined before being used. To
call it, type in the name of the macro instead of a command. You have to use
local labels only in macros, or you will confuse the assembler. You may not
give a name already used as a label name, or some strange things will happen...
Example of a macro:
slowprt mac ;begin macro definition; macro name is: slowprt
ldy #0 ;example code
]lp dey ;always use local labels within macros
bne ]lp
jsr $fded ;print akku content
^^^ ;end of macro definition
Example of a macro call:
lda #"A"+128 ;load akku with letter "A"
slowprt ;print it (slow mode)
There is also the possibility of passing parameters to the macro. Example:
print mac
lda #&1 ;&1 will be the first parameter
and #$7F
ora #&2 ;&2 will be the second given parameter
jsr $FDED
^^^
print "A",$80 ;Pass two parameters to the macro which must be
rts ;seperated by commas.
Important: You may have up to 8 macro parameters per macro call. These parms
are Longword(s). Macros may not call other macros.
The Linker:
-----------
The Linker, which is enabled when the assembler finds a LNK command in the
source, will generate an OMF 2 GS/OS loadfile with only one segment. The
segment header is generated immediately when an LNK command has been found.
Errors:
-------
Besides of the standard P8 errors that may occur during loading/saving source/
output file, there are these assembler Errors:
Unknown directive or command. Mostly typing errors (e.g.: LAD instead of
LDA etc.) NF AS stops assembling.
Incorrect Hexadecimal value. Formal error.
Incorrect Decimal value. Formal error.
Incorrect Binary value. Formal error.
Illegal Operand structure. Formal error.
Undefined Label. Undefined Label was used.
Branch too long. The destination from the Program Counter
to the address specified by a branch-command
is too long. NF AS stops assembling.
Import file not found. The file specified by the IMP command not is
present.
Illegal macro call. There is no macro with the given name.
Macro header is missing. A macro end command (^^^) was found without
a macro begin command (MAC) before it.
Undefined macro parameter. A macro asks for another parameter that is
missing in the parameter list of the macro
call.
Division by zero. The divisor of a math operation was zero.
Can't make more than 8 loops. NF Assembler can only build 8 loops inside
each other.
Loop definition is missing. A <<< command was found without a LOP.
Value is unknown. The operand value is undefined. Mostly,
this occurs when a label is specified
in the operand that is defined later. When
you get this error, you should move the
label before the operation producing the
error.
Debugger:
---------
There is a debugger where you can select variables that you want to watch
during program execution. You can enter the debugger through the Editor (in the
'Assembler' menu), by select 'NF Debugger' from the CDA menu or when a break
occurs and you set the Debugger so that it intercepts break commands. A small
help is provided in the debugger, which tells you more about itself, and I
guess the other options are self-explanatory.
Special notes:
--------------
- The assembler is case-sensitive in terms of labels and macro names, but not
with commands (LDA,STA etc...)
- simple math operations may be used (only +, -, * and /):
$15-%1100 or "a"+15-label+$40
label*"Hi" or label/17
Important: The assembler does not recognize math rules: Operations are calc-
ulated one after each other, so 10+10*10 is 200, but 10*10+10 is 110. Ok,
this is lame, but mostly you don't calculate very much...
- Labels may be up to 25 letters long. There is, once again, no check for that.
- Labels may not be used twice or the second is ignored (no error reported).
- Zero page and LongWord Labels must be defined before they can be used !!!
- You may force the Long addressing mode by typing an "L" after the command.
Example: LDAL $1000 will result in LDA $001000
- Always tell the assembler what type (16 or 8 bits) of registers you use. When
assembly begins, NF.AS is set to LNG, that is 16 Bits all registers. (So it
is not necessary to write a LNG at the beginning of the Source).
- Max. Source Length is 64k.
- When INSerting a second source code, the state of all internal assembler bits
(size of akku,x,y or msb etc.) will not be changed. An ORG command in the
inserted source will be ignored. Also, the second source shares all macros
and labels with the main code. Use the INS command for including macro and
label files and for splitting extreme long sources.
- Look at the Sample Source codes for an example of coding with NF AS.
(You should print this reference if you want to program with NF AS.)
Editor Documentation
Quick documentation for NF Editor
---------------------------------
The best for working with the NF.AS.ED is to make a disk with ProDOS 8, and
Basic.System and launch the editor from Basic, since you will have the ProDOS
Shell option then and can quickly exit and enter the assembler.
1. Memory requirements
NF Assembler / Editor needs at least 608K of extra memory. More memory will be
required when you connect source codes using the INS command or activate the
linker (described in the assembler documentation). Please note that you can
change the amount of memory for the output file in the preferences (see below).
2. Entering text
You can enter only 79 chars per line. Lines longer than that are not shown in
their full size, but are not truncated. Note that the assembler does not
require such long lines (so don't use them). Lines longer than 255 chars will
cause strange things... so don't load in your scrolltexts! 64K are allocated
for edit buffer. There is a display that shows how many bytes are still free.
Press esc or the mouse button to enter menus and use the arrow-keys or mouse
to select, then press mouse button or return to execute function or esc to
leave menus.
3. Command keys (OA = open apple key)
return insert line
delete delete character before cursor
arrows move the cursor
esc enter pull-down menus (use arrow-keys to move in menus)
tab jumps to next tab position (as displayed in line 3)
OA tab sets or unsets tab pointer at cursor location
OA -> jumps to next word in the current line
OA <- jumps to previous word in the current line
OA down-arrow jumps down one page
OA up-arrow jumps up one page
OA > and OA . jumps to end of line
OA < and OA , jumps to begin of line
OA 1 jumps to begin of text
OA 2..8 jumps to positions somewhere in the text
OA 9 jumps to end of text
OA E toggles cursormode: insert or overwrite
OA C copies selected text to the editor clipboard
OA X copies selected text and deletes it in the text memory
OA V paste (insert) previously selected text behind cursor
OA DELETE deletes selected text (same as 'Clear' in the Edit-menu)
OA Y erases all characters after cursor to the end of line
OA W deletes word under cursor
OA T erases line under cursor
OA B inserts a line under cursor
OA F finds text from the beginning
OA G find again from cursor position downward
OA L goto label (does not work properly on local labels, of course)
OA R Finds and Replaces text from cursor position downward. First
enter the string to search for, then enter the replace string
(which is always case sensitive) and type A or M for automatic
or manual replace. Press esc to back up here. Manual will
check each time the string is found. Press Y to replace, N no
replace, A to auto-replace from there on and esc to leave
replace.
OA N clear memory
OA M define macros (see below)
OA O open source file
OA S save source file (quick save)
OA D enter ProDOS command shell (see below)
OA A assembles editor text and ERASES the clipboard !
OA ? credits - the most important feature
option-A to
option-Z activate macro A to Z
4. Special menu items
Load clipboard
You can load in a second source code at any time directly to the clipboard,
then paste it where you want to have it using the paste command. This is to
put together two files very easily.
ProDOS Shell (OA-D)
Anything you type in is going to be sent to the Basic Interpreter, which works
only if you started the editor from Basic. Enter Q and Return to exit. Use the
shell to switch to other directories or to catalog them. A new ProDOS command
will be available under this shell: EDIT filename will switch to the editor
and load in the specified file.
Print
You may print source codes with the print option in the file menu. Output will
be sent to whatever is connected in slot 1. Type W to print all memory contents
or C to print clipboard only.
Macros (OA-M)
You can define up to 26 keyboard macros. Press the specific key (A to Z) to
edit that macro. The old definition will be erased. Type in any key
combination. Control characters will be displayed as inverse characters (for
example, return will be an inverse 'M') You can access the apple-function keys
through the macros as well. You can go through menus, load in files,
automatically find pieces of text... Press option-delete to erase last key
combination and option-esc to leave editing the macro. Once a macro is defined,
you can execute it by pressing option and the macro key (for example option-A
will launch macro A). The editor already comes with some pre-defined macros to
try out. Please note: you can not program the shell with macros.
Preferences
Lets you toggle some options on/off:
* Special assembler text layout - supports the assembler text format.
* Case sensitive find - toggles case sensitivity of find, goto label and
replace functions.
* Cursor overwrites characters - toggles the state of the cursor mode.
* Screensaver active - turns on screensaver / changes the minutes before
Screensaver will be activated.
* Source code filetype is SRC - toggles between TXT and SRC source code types.
When loading a file, this switch is set according to the loaded file type.
* Install Visit Monitor DA - will install Visit Monitor and Memory Peeker DA's.
* Use open/save dialogs - when off, you have to enter filenames manually.
By the way: when a macro is loading a file, this box is used automatically
instead of the file selector box.
* Memory size for output file - You can specify the amount of memory that the
assembler uses to store the output file in. Adjust this number according to
your needs and your memory capabilities. Restart the program to make the
change become effective.
Save preferences
This function will save the preferences, the state of the tab stops and the
macro definitions. You must enter the name of the editor file here, which is
NF.AS.ED. I have chosen this way to save the settings because you may want to
rename the editor file (I renamed mine to ED so that I don't have to type so
much to launch it from Basic).
Enter Debugger
See NF.AS.DOCS for more information.
5. Special notes...
...on the info line:
The info line is located under the menu line. Filename, current line number,
colum and the number of free bytes (hex) are displayed here. You have 64k of
free memory to edit.
...on find/replace:
When entering text strings, press esc to cancel, return to accept, delete to
erase char before cursor and Ctrl-X (which is located next to 'delete' on
the keypad) to erase the entered line.
...on selecting text:
Press OA C to copy text. The selection will appear as highlighted text
lines. Use the up-and-down arrow keys to extend the selection. Press return
to accept the selection and to operate on it (Cut, Copy, Clear) or press esc
to cancel.
...on assembler:
When an error occurs, the assembly process is halted. You then have the
choice: type esc to jump to the place where the error occured or any other
key to continue assembling. A source code that contains errors is not going
to be saved.
The assembler will automatically overwrite files named like the output file.
...on assembler text layout:
The first three tab positions (stops) are important for this mode. The first
one defines the position of the command, the second of the operand and the
third is where the comment begins. Unless you don't enter a comment line, or
edit a comment behind a directive, space will be same as tab, delete will
delete all spaces before the cursor and the arrow keys jump over the spaces.
Use this function to get better looking source codes. (Use this, it's cool.)
Turn this feature off when editing normal ascii text files.
...on source code file formats:
If you turn off 'Source Code filetype is SRC' in the preferences, saved
files will have the current line number stored in the AuxType, like
Merlin 16+.
...on mouse support:
Please note that the moving the mouse is the same as pressing the arrow
keys. Fast Cursor movement is possible: press the open apple key when
moving. Press the button to enter menu.
...on leaving the editor:
Press OA Q for the quit menu, then press Q for ProDOS quit, or E to exit to
Basic (if available).
Print this documentation for quick reference.
Macro Notes
MACRO NOTES
===========
All macros in the MACROS directory and all equates in the EQUATES directory are
copyright (c) Apple Computer and were translated to be used with the NF
Assembler.
When using these Toolset macros, be sure to INSert the equates file belonging
to the macros first. (Have a look at the insert example.)
Macro files are named: Equate files are named:
M16.xxx E16.xxx
|
