ift 0 :label nop eifreported Label not defined before error for the repeat count.
ift 0 label eifreported No ORG specified error for the label definition.
XASM source [options]source is the name of source file. If no extension is given, the .ASX is implied.
Default action on invoking without options is to compile writing to a file with the .OBX extension.
If there was no error, variables point to the last issued warning.
If no warning occured, they are removed from the environment.
Note: NCE is an old editor for DOS. To learn about integration with
modern text editors for Windows read this.
Note: Much more powerful for this purpose is GNU make utility.
In DOS and Windows you may use its DJGPP port (available from
http://www.delorie.com/djgpp).
There are following types of fields:
In the latter form, you must use a minimum of an instruction field.
It depends on the instruction, how many operands it takes.
Every instruction takes constant number of operands, therefore
there's no need to use a special character at the start of a comment, because after
succesfully taking operands, X-Asm discards the remaining part of line.
However, general purpose text editors may highlight
the comments only if a special delimiter is used, and for that reason,
the semicolon is recommended to start a comment.
Single instruction always consists of 3 letters. It may be:
Assembling options
Following options are supported:
If source is incorrect, X-Asm stops on first encountered error.
By default lines skipped due to false condition are not listed.
label should be a valid label name.
value may be any expression (it may use forward references
to labels defined in the source file).
You may use several /d options to define many labels
from the command line.
With this option, X-Asm sets two environment variables:
ERRFILE and ERRLINE.
They may be used in a batch file to locate error and set editor's
insertion point on it. For example, you may create following batch file:
XASM %1 /e
IF NOT ERRORLEVEL 1 GOTO ok
NCE +%ERRLINE% %ERRFILE%
:ok
NCE stands for Norton Classic Editor.
This option is useful for the Code-Genie editor (see
here), which can jump to the error location
only if full path is given.Exit codes
Meaning of exit codes returned by X-Asm:
3 = bad parameters, assembling not started
2 = error occured
1 = warning(s) only
0 = no errors, no warnings
Listing structure
A line of listing contains:
Listed are also generated headers. A xxxx-yyyy> in place of origin
counter represents generated header: $xxxx is the first and
$yyyy is the last byte of the 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.
Label table structure
A line of label table contains:
n - label defined but not used elsewhere
2 - label value known in pass 2 only (label definition uses forward
reference and thus you can't make forward references to that label)
SYNTAX
Fields
Source code is line-oriented. Every line of source consists of fields.
Same sequence of characters used in different fields has completely different meaning.
Fields are separated with one or more blank characters.
There can't be any space within a field, except for strings and comments.
In the first form, both fields are optional. Blank lines are ignored of course.
Comment must here start with one of these characters: ; | or *
(semicolon, pipe or asterisk). Any information in the line following
such character is ignored.Label field
This field is optional. It must start at first character in line, without
any blank characters before. The purpose of using label field is to define a label.
Label is a symbol representing an integer of range -$ffff..$ffff.
Name of a label may contain letters, digits and underscores (_).
Digit can not be label's first character.
Name of a label may be as long as you want and all the characters
are meaningful. In Quick Assembler only 6 leading characters were recognized
and some sources may not compile under X-Asm for this reason.
Defining a label without using EQU makes it equal to current value
of the origin counter.
Labels can't be redefined.Repeat count
Repeating means here assembling single line several times as if
there were several identical lines. Note it is not just duplicating
bytes written to the object file.
Repeat count, which can be any valid expression, has to be preceded
with a colon.
Examples:
:4 asl @
:2 dta a(*)
In the latter example each DTA has different operand value.
If repeat count equals zero, remaining part of line is not assembled.
This allows compact single-line conditional assembly.
Instruction field
If this is the first field in a line, the line must start with at least
one blank character. Instruction field consists of one or two instructions.
The latter case is called instructions pairing, because a pair
of instructions have shared operand. You separate instructions
with a colon.
Example:
adc:sta $80
is equivalent to
adc $80
sta $80
Note that
lda:tax $80
is correct, because $80 is a comment for TAX.
Operand field
Some instructions don't need any operand,
other need two operands.
6502 commands require operand with proper
addressing mode.Comment
Comment in a statement does not start from any special character
like ; for example. Comment field is implied when appropriate
number of operands was taken.Expressions
Expressions are numbers combined with operators and brackets.
You should use square brackets, because parentheses are reserved
for 6502 indirect addressing.
Numbers
Numbers are 32-bit signed integers, in the range of -$7fffffff..$7fffffff.
A number may be:
| -12345 |
| $abcd |
| %10100101 |
| 'a' or "a" |
| * |
| ^4e |
An abbreviation of Atari hardware register is provided to save you trouble of typing two extra characters (^4e vs $d40e) and to support porting software between Atari 8-bit computers and Atari 5200 console. These are very similar machines, one of biggest differences is different location of hardware registers.
(x is a hexadecimal digit).
Syntax Chip Value in Atari 8-bit
computer mode (OPT G-)Value in Atari 5200
game console mode (OPT G+)^0x GTIA $d00x $c00x ^1x GTIA $d01x $c01x ^2x POKEY $d20x $e80x ^3x PIA $d30x error (there's no PIA chip) ^4x ANTIC $d40x $d40x
| {lda #0} |
Single-byte op-code of the instruction inside braces (e.g. value of {nop} is $ea). Operand is discarded and is necessary only for identifying addressing mode. Instruction should begin just after the left brace and the right brace should immediately follow the operand or the command.
You can skip the operand, if the addressing mode is fixed. Examples:
{lda #}, {jsr}, {bne}, {jmp ()}, {sta a:,x}.
| + | Addition |
| - | Subtraction |
| * | Multiplication |
| / | Division |
| % | Remainder |
| & | Bitwise and |
| | | Bitwise or |
| ^ | Bitwise xor |
| << | Arithmetic shift left |
| >> | Arithmetic shift right |
| = | Equal |
| == | Equal (same as =) |
| <> | Not equal |
| != | Not equal (same as <>) |
| < | Less than |
| > | Greater than |
| <= | Less or equal |
| >= | Greater or equal |
| && | Logical and |
| || | Logical or |
| + | Plus (does nothing) |
| - | Minus (changes sign) |
| ~ | Bitwise not (complements all bits) |
| ! | Logical not (changes true to false and vice versa) |
| < | Low (extracts low byte) |
| > | High (extracts high byte) |
Operator precedence:
| first | [] | (brackets) |
| + - ~ < > | (unary) | |
| * / % & << >> | (binary) | |
| + - | ^ | (binary) | |
| = == <> != < > <= >= | (binary) | |
| ! | (unary) | |
| && | (binary) | |
| last | || | (binary) |
Note that although the operators are similar to these used in C, C++ and Java, their priorities are different than in these languages.
Compare and logical operators assume that zero is false and a non-zero is true. They return 1 for true.
While calculating expression, signed 32-bit arithmetic is used. When range of 32 bits is exceeded, 'Arithmetic overflow' error is generated.
Examples:
There are two extra immediate addressing modes:
< and >,
which use low/high byte of 16-bit word constant.
They are for Quick Assembler compatibility.
You can use traditional #< and #>.
Note
In absolute addressing modes, X-Asm examines the expression and uses zero-page
addressing mode if it supposes it's possible. You may override it with
a: and z: prefixes.
Examples:
A: < and > are not only 'low' and 'high'
operators, but also 'low of immediate' and 'high of immediate'
addressing modes indicators.
In order to get lda $ab, write lda +>$abcd
A: You must use @ for accumulator addressing mode.
A: You should have explicit run address specified.
Use run start directive. end takes no operand.
Example:
A: X-Asm displays only first error.
Directives
Examples:
five equ 5
here equ *
You can turn any of these on or off.
Default (if no OPT specified) is opt f-g-h+l+o+.
Examples:
opt l- listing off
opt l+o- listing on, object file off
opt f+g+h- useful for Atari 5200 cartridges - raw output format, 5200 hw regs
Examples:
org $600
org f:$700
table org *+100
In the latter example table points to 100 bytes
of uninitialized data (label is assigned to *
before ORG directive is executed).
Examples of DTA:
You may enter many expressions in parentheses and combine different types
of data in single line, separating things with commas.
You may also define a sine lookup table. Syntax is:
sin(centre,amp,size,first,last)
where:
Example: dta a(sin(0,1000,256,0,63)) defines table of 64 words
representing a quarter of sine with amplitude of 1000.
Real numbers are written in 6-byte Atari Floating-Point format. You can't
combine reals with operators, as you can integers.
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
high bit in every byte of string.
dta b(1,2),3,a(1000,-1),l(12345,sin(0,127,256))
dta d"ANTIC"*,c'It''s a string',$9b
icl 'macros.asx'
icl 'c:\atari\xasm\fileio'
Example:
end
You may specify range of inserted file. Syntax is following:
ins 'file'[,offset[,length]]
First byte in file has offset 0.
If offset is negative, it is counted from the end of file.
Examples:
ins 'picture.raw'
ins 'file',-256 insert last 256 bytes of file
ins 'file',10,10 insert bytes 10..19 of file
run addr
is equivalent to:
org $2e0
dta a(addr)
Examples:
run start
run main
Examples:
ini init
ini showpic
ert *>$c000
ert len1>$ff||len2>$ff
ELI - else if
ELS - else
EIF - end if
Example:
noscr equ 1
widescr equ 1
ift noscr
lda #0
eli widescr
lda #$23
els
lda #$22
eif
sta $22f
Above example can be rewritten using line repeating feature:
noscr equ 1
widescr equ 1
:noscr lda #0
:!noscr&&widescr lda #$23
:!noscr&&!widescr lda #$22
sta $22f
Pseudo-commands
Pseudo-commands are built-in macros.
They are not unofficial instructions, so they work on typical 6502.
X-Asm can do it for you. ADD replaces two instructions:
CLC and ADC.
Example:
ldx #0
mva:rne $500,x $600,x+
The example code copies memory $500-$5ff to $600-$6ff.
Here is the same written with standard 6502 commands only:
ldx #0
loop lda $500,x
sta $600,x
inx
bne loop
Example:
lda #40
add:sta $80
scc:inc $81
In the above example word-size variable $80 is incremented by 40.
Nor conditional repeat nor skip pseudo-commands require operand,
thus they can be paired with any other command.
Example:
jne dest
is equivalent to:
seq:jmp dest
Example:
inw dest
is equivalent to:
inc dest
sne:inc dest+1
mva source dest = lda source : sta dest
mvx source dest = ldx source : stx dest
mvy source dest = ldy source : sty dest
You can't use indirect nor pseudo addressing mode with MW*.
Destination must be absolute address (optionally indexed).
When source is also absolute, a mw* source dest will be:
mv* source dest
mv* source+1 dest+1
When source is an immediate, a mw* #immed dest will be:
mv* <immed dest
mv* >immed dest+1
When <immed equals >immed and immed
is not forward-referenced, X-Asm uses optimization:
mv* <immed dest
st* dest+1
If possible, MWX and MWY use increment/decrement
commands. E.g. mwx #1 dest is assembled as:
mvx #1 dest
dex
stx dest+1
Addressing modes
All addressing modes are entered in standard convention except
the accumulator addressing mode, which should be marked with a
@ character (as in Quick Assembler).
nop
asl @
lda >$1234 assembles to lda #$12
lda $100,x
lda a:0 generates 16-bit address
jmp ($0a)
lda ($80),y
There are also pseudo addressing modes, which are similar to
pseudo-commands. You may use them just like standard addressing modes
in all 6502 commands and pseudo-commands, except for
MWA, MWX and MWY:
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
cmd (z),0+ = ldy #0 : cmd (z),y : iny
cmd (z),0- = ldy #0 : cmd (z),y : dey
FAQ
Note: All the following things, which may be odd for you,
are familiar to Quick Assembler users.
If you have other questions/problems,
contact me.
label equ 1 +2
A: X-Asm treats space as operand terminator. Remaining part of line
is a comment. You should write 1+2 without any spaces.label: lda #0
A: Label definition can not include a colon.three equ one+two
two equ one+one
one equ 1
while this does:
two equ one+one
one equ 1
A: X-Asm reads source twice (in pass 1 and pass 2)
from the beginning until the end.
This allows forward references, but not too complex.
Keep in mind that the assembler must know all the values in the second
pass.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 two passes.
If you insert following statement as first line:
three equ one+two
X-Asm will generate an error because it can't fix
the value of three in second pass.
When you were assembling for the first time, both errors might exist,
but X-Asm stopped on the first one.