ST-65 Cross-Assembler Manual

Freddy Offenga, 2003-06-04

Introduction
With the ST-65 assembler you can assemble hundreds of kilobytes source code into executable code for the Atari 8-bit on your Atari ST/E.

The Assembler Shell
The shell is the interface between the required programs you need to create executable code from a source code.

Desk:
Shows the copyright and possible accesories.

File:

• [D] Work file
  Select the work source file
• [P] Paths
  Indicate where the shell can find the assembler, editor and additional programs
• [S] Save work
  Saves all the adjustments (A_SHELL.INF)
• [Q] Quit
  Back to the desktop.

Assembler:

• [A] Assembler
  Execute the ST-65 assembler
• [E] Editor
  Execute the editor
• [O] Options
  Select the assembler options

Execute:

• [G] Execute
  Execute any file (it will ask which one)
• [1] Execute program 1
• [2] Execute program 2
• etc...

Choices can be activated by using the mouse or by pressing ALTERNATE together with the named character.

If you execute the assembler, a window will appear were you can make several adjustments (explained later). If you don't enter a path for 'output', 'list' or 'symbol', the these files will be directed to the same directory as where the source file is located. If you use an editor which allows more than one file in the command line (e.g. Tempus), it will load both source and error file.

The Assembler

Syntax: ASS_6502 [OPTIONS] [SOURCE FILE] [OBJECT FILE]

The parameters should be separated with spaces. Options always begin with a "-" sign. You can use more options at the same time as long as they're seperated with spaces. The following options are possible:

• -B : JMP statements are changed into BRA statements wherever it's possible.
• -C : 65C02 instructions are possible.
• -E : List include files also.
• -H : The output assembled code will be in "hexstring". The first four characters indicate the start address (Low/High), the next four indicate the end address (Low/High). Then follows the code in ASCII. Binary code has the extension ".65" while ASCII files have the extension ".H65". If the output is set to binary or to hex, a forward ORG fills the memory from the end pointer to the next (forward) ORG. Backward ORG commands are not allowed in these modes.
• -I : Use this option if you want to get intel HEX files!
• -Z : Switch off zero page adr.
• -X : Object code will be in XL/XE format. It will generate a file with the same format as a normal "COM" file. RUN or INIT addresses can be included directly into the source by using ORG $02E0 (RUN) or ORG $02E2 (INIT).
• -F=FILE : Errors will be put in "FILE".
• -L=FILE : Output listing will be put in "FILE".
• -S=FILE : Output symbols will be put in "FILE".

The object filename is build from the source filename with the extension ".65" or ".H65" (hexstring).
All options included in the source code have priority.


SOURCE CODE FORMAT
The source can be made by any ASCII wordprocessor. Symbols always start at the first position. All other fields can begin at any position as long as they're seperated by spaces or TABs. Ofcourse using the TAB key is recommended because this will result in a much better readable source.

Symbols should always start with a character. After that characters, numbers and "_" are possible. Small characters and capitals are both possible, but beware of the fact that they're handled as different symbols. So "LABEL" is not the same as "label"!

All mnemonics of the 65xx processors are possible. Also mnemonics can be written in small characters or capitals and they're handled the same way (Lda = LDA).

Registers like "A", "X" and "Y" can also be written as "a", "x" and "y". Hexadecimals may be small characters or capitals ($ff = $FF).

Numbers in operants can be decimal, hexadecimal or binary. "$" indicates hexadecimal, "%" indicates binary.

A number or symbol followed by ".H" or ".h" results in the high byte of that number or symbol (number DIV 256).
A number or symbol followed by ".L" or ".l" results in the low byte of that number or symbol (number MOD 256).

An operant expression may contain +, -, * and /. The expression is evaluated from left to right and the priority can not be changed. Brackets are not possible. Avoid difficult expressions.

Remarks are in the fourth field or begin with ";".


ASSEMBLER OUTPUT
If needed the assembler can generate a listing from the source code. The format of the listing is:

nnnn xxxx yy yy yy label mne operant

• nnnn
  Line number
• xxxx
  Address
• yy
  Hexadecimal code
• label
  Label (if used)
• mne
  Mnemonic
• operant
  Operant

The assembler can generate a list of all the symbols used in the source code. Just the first 10 characters of the symbol are generated. The symbols are generated in order of appearance.


ASSEMBLER DIRECTIVES

EQU (Label EQU expression)
Bind a label to an expression.
Example:
TEST  EQU $1000 ; TEST equals $1000

ORG (ORG expression)
Initialize the start address of the code. There can not be a label in front of an "ORG". The expression may not contain forward references.

BND (BND expression)
The expression should be a number which is a power of two, like 1,2,4,8,16 upto 2^15 (32768). Normally you would use the ORG command to locate a new pointer, but the BND command will simply calculate the first usable boundary and perform an ORG at this address. For example:
        ORG $A800

        LDA #FONT.H
        STA 756
        RTS

        BND $0400           ; next 1K boundary
FONT    DATA FONT.FNT       ; include font data


DFB, DFA, DFW:
DFx (Label DFx expr. <,expr.>)
Define constants in memory.

DFW is used to define words (high,low order)
DFA is used to define words (low,high order)
DFB is used to define bytes (expr. MOD 256) or characters. Characters must be between '' (like 'example'). Screen code is the specific Atari 8-bit code directly usable as screen memory without translation.
The options for DFB are:

DFB 10,20,30,40
DFB    'normal ascii'
DFB.I  'invers ascii'
DFB.A  'screen code'
DFB.AI 'invers screen code'

RES (Label RES expression)
Fills "expression" bytes with $FF.

INCLUDE (Label INCLUDE filename)
Inserts a choosen source file. This way you can directly add small routines to the main source listing.

DATA (Label DATA filename)
Inserts a choosen data file directly into the object code. Data files will be inserted literal!

OUTPUT (OUTPUT filename)
Select the output filename (object code).

LIST (LIST filename)
Select the output filename of the listing.
Use LIST con: to display the listing on screen.
Use LIST prn: to print the listing.

SYMBOL (SYMBOL filename)
Select the output filename of the symbol list.
Again just the first 10 characters of a symbol are generated. Also use "con:" and "prn:" to display or print the symbol list (see LIST).

OPTION (OPTION opt <,opt....>)
Select options. You can activate or disable all the described options (like Z, B, C, L, E, H and X).
To activate an option, use opt+ (example Z+)
To disable an option, use opt- (example Z-)

FAIL (FAIL <'message'>)
Generates an error. This can be useful for macros. For more information take a look at the macro library.


CONDITIONAL ASSEMBLY

Syntax:
   IFC expr.1 equation expr.2
     .
     Assembler block
     .
   ENDC

IFC..ENDC allowes conditional assembly of a code section. If expr.1 equation expr.2 is true then the piece of source code between IFC and ENDC is going to be assembled. Otherwise it will skip that section. An IFC..ENDC can be within other IFC..ENDCs.

Expr.1 and expr.2 may not include forward references.
Equations: =, #, < and > (# means NOT EQUAL).


MACROS

Macro definition:
   Name    MACRO
             .
             .
             Assigned block
             .
             .
           ENDM

MACRO..ENDM is used to define a macro. 'Name' may not be a mnemonic or directive. Macros can include further macros. The macro should be defined before using. Labels are not allowed within a macro, but structure blocks are.

Macro parameters:

Parameters can be used within a macro by \n. There are a maximum of 10 parameters possible (\0..\9). Parameters may only be in the operand field. \n will be replaced by parameter n in the text. NARG or narg can be used to count the number of arguments (parameters).

Macro call:
<Label>   Name <Parameter,..>

The macro will be called if the name is in the mnemonic field. The parameters are in the operand field. Calculations and strings are legal parameters.

Macro exit

  MEXIT

With MEXIT you can exit the macro premature.


STRUCTURE BLOCKS

Structure blocks allow structured programming. It should not be compared with conditional assembly. Structure blocks may not exceed 128 bytes (same as a branch) except for DO..LOOP.

IF..ENDIF - condition.

Syntax:
<Label>    IF cond
             .
             Assigned block
             .
          ENDIF

Generated code:
<Label>    BCC Label_0
             .
             Assigned block
             .
Label_0    continue program.

IF..ELSE..ENDIF - condition.

Syntax:
<Label>   IF cond
             .
             Assigned block
             .
          ELSE
             .
             Assigned block
             .
          ENDIF

Generated code:
<Label>   BCC Label_0
             .
             Assigned block
             .
          JMP Label_1
Label_0      .
             Assigned block
             .
Label_1   continue program

DO..LOOP - Endless loop

Syntax:
<Label>   DO
             .
             Assigned block
             .
          LOOP

Generated code:
<Label>      .
             Assigned block
             .
          JMP <Label>

REPEAT..UNTIL - Conditional loop

Syntax:
<Label>   REPEAT
             .
             Assigned block
             .
          UNTIL cond

Generated code:
<Label>      .
             Assigned block
             .
          BCC <Label>

BEGIN..WHILE..WEND - Conditional Loop

Syntax:
<Label>   BEGIN
             .
             Assigned block
             .
          WHILE cond
             .
             Assigned block
             .
          WEND

Generated code:
<Label>      .
             Assigned block
             .
          BCC Label_0
             .
             Assigned block
             .
          JMP <Label>
Label_0   continue program

As 'cond' (condition) are allowed: EQ, NE, CS, CC, PL, MI, VC, VS. The output code will contain branches with the opposite of the condition.


ADDITIONAL NOTES

the program pointer can be called by using @.
For example:
    ORG 1234 ; ORG 1234
    JMP @    ; JMP 1234

If the 65c02 mode is active, the assembler defines a symbol CMOS. You can check this symbol like this:

    IFD CMOS
        ;specific 65c02 code
    ENDC

It will assemble the specific 65c02 code if CMOS is defined. The opposite is also possible:

    IFND CMOS
        ;normal 65c02 code
    ENDC