xasm/xasm.txt

X-Assembler version 2.0
=======================
coded by Fox/Taquart

INTRODUCTION
============
The X-Assembler is an assembler, which generates code for the 6502 processor.
It is 99% compatible with Quick Assembler on 8-bit Atari.

System requirements
-------------------
- a PC compatible computer with 386 or better CPU
- a MS-DOS compatible OS
- a numeric coprocessor for generating sinus tables
  Your CPU probably has a built-in coprocessor.

Creating a source program
-------------------------
Source file should be standard text file with IBM-style EOLs: CR/LF. You can
use any text editor on PC to prepare your source code.
Single line of source should not be longer than 256 characters.
There is no limitation on the length of the file.
Source may contain tabulators - there are treated as spaces.
Assembler is NOT case-sensitive.

Converting Quick Assembler files
--------------------------------
You must convert Atari text file into PC text file (EOL's from $9b to $0d/$0a),
ATASCII 0-31 and 128-255 characters should be replaced with standard ASCII
characters, using QAsm expressions.
You also have to change all OPT directives, but usually you needn't them
at all.

Assembling a source program
---------------------------
Syntax (parameters in brackets are optional):
XASM source [options]
'source' is name of source file.
If no extension given, the .ASX is added by default.
Options are:
/c
Enable listing false conditionals.
/i
Disable listing included source.
/l[:fname]
Enable generating listing. If no fname given, listing is written to source.lst.
/o:fname
Specify object name. Default is source.obx.
/s
Disable converting spaces to tabs. Using tabs makes listing file shorter.
Tab stops are assumed to be every 8 characters.
/t[:fname]
List label table. If no fname given, table is written at the end of listing.

If source is incorrect, X-Asm displays ONLY FIRST encountered error.

Errorlevels returned by X-Asm:
3 = bad parameters, assembling not started
2 = error occured
1 = warning(s) only
0 = no errors, no warnings

Listing structure
-----------------
Line of listing includes:
- decimal number of line of source file (if source is different than in
previous listed line, appropriate message line is generated)
- hexadecimal origin
- hexadecimal bytes written to object file
Listed are also generated headers. A 'xxxx-yyyy>' in place of origin is
a generated header: $xxxx is the first and $yyyy is the last byte of block.
A 'FFFF>' represents two $ff bytes written as a header prefix.
A plus sign placed after hex numbers stands for more bytes written to object
in this line, not listed through lack of space.
- remaining part of listing line is a copy of source

Label table structure
---------------------
Line of label table includes:
- some info of label:
  n - label not used
  2 - label value known in pass 2 only (label definition uses forward reference
      and thus you can't do forward references to that label)
- hex value of label
- name of label

X-ASM LANGUAGE STRUCTURE
========================
Lines of source code may be:
- empty lines - ignored, of course
- comments - ignored, too
- statements - not ignored :-)
Comment lines must have one of the following characters in the FIRST column
of the line: * ; |

Numbers
-------
Numbers are 32-bit signed integers, in the range of -$7fffffff..$7fffffff.
A number can be:
- a decimal number          -12345
- a hexadedecimal number    $abcd
- a binary number           %10100101
- a character               'a' or "a" (new in 2.0!)
- a hardware register       ^31
- an origin counter         *
I think only 'a hardware register' should be explained. It is a short way
of accessing Atari hardware registers:
^0x means $d00x
^1x means $d01x
^2x means $d20x
^3x means $d30x
^4x means $d40x
where x is a hexadecimal digit.

Expressions
-----------
Expressions are numbers combined with operators and brackets.
You should use square brackets, because parentheses are reserved
for 6502 indirect addressing. Currently there are 19 operators:

+  Addition
-  Subtraction
*  Multiplication
/  Division
%  Remainder
&  Bitwise and
|  Bitwise or
^  Bitwise xor
<< Arithmetic shift left
>> Arithmetic shift right
=  Equal
<> Not equal
!= Not equal (same as <>)
<  Less than
>  Greater than
<= Less or equal
>= Greater or equal
&& Logical and
|| Logical or

Operator precedence:
first  []
       * / % & << >>
       + - | ^
       = <> != < > <= >=
       &&
last   ||

Compare and logical operators assume that zero is false and non-zero is true.
They return -1 for true.
When calculating expression, 32-bit arithmetic is used. When range of 32 bits
is exceeded, 'Arithmetic overflow' error is generated.
If result of expression has improper size, 'Value out of range' error occurs.
Note difference beetwen X-Asm 2.0 and QAsm/X-Asm 1.2: in older assemblers,
which used 16-bit arithmetic, a LDA 0-1 was correct (LDA $ffff), but X-Asm 2.0
encounters an error: address can't be negative.
X-Asm recognizes now signed bytes: LDA #-1 is OK.

Statements
----------
A statement is divided into fields: a label field, an operation field,
one or two operand fields, and a comment field. There should be at least
one space between every two fields and there can't be any space within a field
excluding strings.

Label field
~~~~~~~~~~~
This field is optional. It is required only by the EQU directive.
Specyfying this field definies a label. Defined label represents an integer
of range -$ffff..$ffff.
Name of label must begin in column 1 and can contain letters, digits
and underscores (_). Digit can't be label's first character. Name of label
can be as long as you want and all the characters are meaningful.
In Quick Assembler only 6 leading characters were recognized
and some programs may not compile well under X-Asm for this reason.
Defining a label without using EQU makes it equal to current value
of the origin counter. Label can't be redefined.

Operation field
~~~~~~~~~~~~~~~
Operation field is the only field which is always required.
You have to put one or more spaces or tab characters between label
and operation field. If no label is defined, line must start with a blank
character. Operation field is always 3 letters long. It can be:
a. a 6502 processor command
b. a compiler directive
c. a pseudo-command

a. 6502 command
One of 56 well known processor commands.

b. compiler directive
One of the following:

EQU - assign a value of expression to the label
Note that label represents a number, not a text macro.
Examples:
five equ 5
ten  equ five+five

OPT - set assembling options
Currently there are two options: listing generating and headers generating.
You can turn any of these on or off.
Examples:
 opt l-    listing off
 opt h-    headers off
 opt l+h-  listing on, headers off
Remember not to put a space between options:
 opt l+ h-
is actually
 opt l+
because h- is a comment.
Default (if no opt specified) is opt l+h+.

ORG - set new origin counter
Examples:
 org $600         code will be located starting from $0600
table org *+100   'table' points to 100 bytes of uninitialized data
New! You can set some options applied to new header (if headers are on):
 org $600
 rts
 org a:$601
'a:' tells X-Asm to always make a header, even it is unnecessary (as in above).
So by default X-Asm 2.0 does not generate unnecessary headers, distinct from
QAsm and X-Asm 1.2.
 org f:$700
'f:' works same as 'a:', but additionally tells to generate a $ff,$ff prefix
before header. X-Asm adds it to the first header in file by default, so use
this option only if you want the $ff's somewhere inside.

DTA - define data
You may define:
* numbers
  - bytes: b(200)
  - words: a(10000)
  - low bytes of words: l(511) defines byte 255
  - high bytes of words: h(511) defines byte 1
  You may enter many expressions in parentheses and combine different types
  of data in single line.
  You may also define a sinus table. Enter this expression:
  sin(centre,amp,size,first,last)
  where:
  - centre is a number which is added to every value of sinus
  - amp is the amplitude of sinus
  - size is the period of sinus
  - first,last define range of values in the table.
    They are optional. Default are 0,size-1.
  Example: dta a(sin(0,1000,256,0,63)) defines table of 64 words representing
  a quarter of sinus with amplitude of 1000.
  - real numbers: r(-1.23456e12)
  Real numbers are written in 6-byte Atari Floating-Point format. You can't
  combine reals with operators, as you can integers.
* text strings
  - ASCII strings: c'Text' or c"Text"
  - ANTIC strings: d'Text' or d"It's something new!"
  A character string consists of any of characters surrounded by quotation
  marks. Within a string, a single quotation mark character is
  represented by two succesive quotation marks.
  Placing a '*' character after a string inverts bit 7 in every byte of string.
Examples of DTA:
 dta b(2,5),a(1000,-1),l(12345,sin(0,127,256))
 dta d"ANTIC"*,c'It''s a string',b(155)

ICL - include another source file
Specifies another file to be included in the assembly as if the contests of
the referenced file appeared in place of the ICL statement. The included file
may contain other ICL statements.
Examples:
 icl 'macros.asx'
 icl 'c:\atari\xasm\fileio.asx'

END - end assembling of file
Remaining part of the file is not assembled. If this statement does not occur,
assembler stops assembling when encounters end of file.
Example:
 end

INS - insert contents of file
Copies every byte of specified file into object file and moves origin counter,
as if these bytes were defined with DTA.
Examples:
 ins 'picture.raw'
 ins 'tables.dat'
New! You may specify range of inserted file. Syntax is:
 ins 'file'[,offset[,length]]
First byte in file has offset 0.
If offset is negative, it is counted from the end of file.
 ins 'file',-256   inserts last 256 bytes of file
 ins 'file',10,10  inserts bytes 10..19 of file

RUN - generate run address
The Atari executable program should have run address specified. Remember that
a program may be loaded in many areas of memory and started from any address.
 run addr
is equivalent to:
 org $2e0
 dta a(addr)
Examples:
 run start
 run program

INI - generate init address
The Atari executable program may have some routines which are executed during
loading process. There may be many init blocks in one file.
Examples:
 ini init
 ini showpic

ERT - generate error if expression is true
Examples:
 ert *>$c000
 ert len1>$ff||len2>$ff

IFT - assemble if expression is true
ELS - else
EIF - end if
Example:
noscr equ 1
 ift noscr
 lda #0
 els
 lda #$22
 eif
 sta $22f

c. pseudo-command
It is something like built-in macro. It replaces two or more standard
processor commands. Note that it is not an illegal instruction and works
on typical 6502.

ADD - addition without carry
If you ever programmed 6502, you must have noticed that you had to use a CLC
before ADC for every simple addition.
X-Asm can do it for you. ADD simply replaces two instructions: CLC and ADC.

SUB - subtraction
It is SEC and SBC.

JNE, JEQ, JCC, JCS, JPL, JMI, JVC, JVS - conditional jumps
They are a kind of 'long' branches. While standard branches (BNE, BEQ) have
range of -128..+127, these jumps have range of all 64 kB.
For example: a JNE DEST is replaced with:
 beq *+5
 jmp dest

INW - increment word
It is a 16-bit memory increment command. An INW DEST will be replaced by:
 inc dest
 bne _skip
 inc dest+1
_skip equ *
The '_skip' label is not declared of course.

MVA, MVX, MVY - move byte using accumulator, X or Y
These pseudo-commands require two operands.
 mva source dest = lda source : sta dest
 mvx source dest = ldx source : stx dest
 mvy source dest = ldy source : sty dest

MWA, MWX, MWY - move word using accumulator, X or Y
Also require two operands. They are something like combination of two MV*'s:
one to move low byte, and the other to move high byte.
You can't use indirect nor pseudo addressing modes with MW*.
Destination must be absolute address (indexed or not).
When source is also absolute, a MW* SOURCE DEST will be:
 mv* source   dest
 mv* source+1 dest+1
When source is immediate, a MW* #IMMED dest will be
 mv* <immed dest
 mv* >immed dest+1
but when <IMMED = >IMMED and IMMED is not forward-referenced,
X-Asm uses optimization:
 mv* <immed dest
 st* dest+1

Operand
~~~~~~~
It depends on the operation field. Some statements don't need an operand
or need two operands.

6502 commands require operand depending on the addressing mode.
Addressing modes should be entered in standard convention except
the accumulator addressing mode, which should be marked with a '@' character
(as in Quick Assembler).

There are two extra immediate addressing modes: < and >, which use low/high
byte of word is used rather than byte value.

In absolute addressing modes, X-Asm examines expression and uses zero-page
addressing mode if it thinks it is possible to do it. You may override it
with 'a:' and 'z:' prefixes.

Examples:
 nop
 asl @
 lda >$1234	assembles to lda #$12
 lda $100,x
 lda a:0	generates 16-bit address
 jmp ($0a)
 lda ($80),y

New! X-Asm 2.0 brings pseudo addressing modes. They are similar to
pseudo-commands and you may use them as standard addressing modes
in all 6502 commands and pseudo-commands, excluding MW*:
 cmd a,x+    =  cmd a,x   : inx
 cmd a,x-    =  cmd a,x   : dex
 cmd a,y+    =  cmd a,y   : iny
 cmd a,y-    =  cmd a,y   : dey
 cmd (z),y+  =  cmd (z),y : iny
 cmd (z),y-  =  cmd (z),y : dey
 cmd (z,0)   =  ldx #0    : cmd (z,x)
 cmd (z),0   =  ldy #0    : cmd (z),y

Problems
--------
These notes may help you solve problems:

* No spaces are allowed within a field.
label equ 1 + 2
causes label to be equal 1 ('+ 2' is treated as a comment).

* < and > represent addressing modes rather than LOW and HIGH operators.
You specify 'lda <table', not 'lda #<table' like in most 6502 assemblers.

* Label definition does not include a colon
label: lda ^4b     ERROR - colon after label name

* Exactly one run address should be specified
Remember that unlike in other assemblers
 end start
does not tell the assembler that 'start' is the run address (it is a comment).
You must specify the run address with RUN directive.

* X-Asm reads source twice (in pass 1 and pass 2)
This allows forward references, but not too complex.
Keep in mind that assembler should know all the values in second pass.
Example:
two   equ one+one   This value is known in 2nd pass only
one   equ 1         This value is known as early as in 1st pass
These values can be fixed in 2 passes.
But if you insert following statement as first line:
three equ one+two
X-Asm will generate an error because it doesn't know the value of 'three' in
second pass.
(sorry for v1.2 users: EQU forward reference didn't work at all).

* X-Asm displays only first error
When you correct one error don't be surpised if you get another one.

* If you encounter X-Asm works improperly, please let me know.

===