NF Assembler Documentation



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.


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
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


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.


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
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
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


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
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.

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.

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

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

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: