xasm is a free tool for programming old 8-bit computers based on the 6502 processor.
-First version of xasm was written in 1998. I needed a cross-assembler -that could understand the syntax of Quick Assembler -which I used for 8-bit Atari programming before I got a PC. -Initially xasm supported the syntax of QA and nothing more. -I quickly realized that I could extend the syntax to make it more expressive. -This led to xasm 2.0, still in 1998. I added some more features -next year. In 2002 I released many versions which contained -mostly bugfixes. In 2005 there were some minor enhancements and bug fixes, -as well as the whole assembler was rewritten from the x86 assembly language -it was initially written in to the -D programming language. -The rewrite introduced a bug, hopefully fixed in version 3.0.1 -released 22nd April 2007.
-6502 assembler code is usually full of LDA, STA, LDA, STA sequences. -With xasm you can use MVA as a shortcut for LDA/STA pair -or even MWA for 16-bit transfers. You can avoid defining labels -when you need short jumps, thanks to conditional skip -and repeat pseudo-instructions. You can put two instructions -that share their argument in one line. -These are just some of the features that help you program -in a more concise way. Let's look at typical 6502 code -(which is valid in xasm):
-- lda #<dest - sta ptr - lda #>dest - sta ptr+1 - ldx #192 -do_line - ldy #39 -do_byte - lda pattern,y - sta (ptr),y - dey - bpl do_byte - lda #40 - clc - adc ptr - sta ptr - bcc skip - inc ptr+1 -skip - dex - bne do_line --
Using xasm features this code can be rewritten to:
-- mwa #dest ptr - ldx #192 -do_line - ldy #39 - mva:rpl pattern,y (ptr),y- - lda #40 - add:sta ptr - scc:inc ptr+1 - dex:bne do_line --
xasm is a command-line tool so you additionally need a general-purpose text editor. -I use SciTE. -Syntax highlighting definition for it is included with xasm. -To install it, copy xasm.properties to the SciTE directory, -select Options / Open Global Options File, type import xasm -at the end and save the global configuration file.
-
For other systems, such as GNU/Linux and MacOS X, install the latest D compiler -and compile xasm from source code.
-Need a good decompression routine for 6502? -See my inflate routine.
-xasm - 6502 cross-assembler
-xasm source [options]
-xasm is a cross-assembler which generates code for the 6502 -processor.
-source is the name of the source file. If no filename extension -is given, .asx is appended. The default action (when invoked without -options) is to assembly source, writing the result to a file with -the .obx extension.
-Alternatively, you may use Unix-style options, for example:
-xasm -i -d DEBUG=1 -l listing.lst source.asx --
Source files should be plain ASCII files. LF, CR, CR/LF and Atari line terminators -are supported. Labels and instructions are case-insensitive.
-xasm is backward compatible with Quick Assembler. -To compile QA sources with xasm, simply replace ATASCII-specific characters -with their integer codes. You also have to change all OPT directives, -but usually you can simply remove them.
-A label is a symbol that represents a 32-bit signed integer. -You can define a label by putting its name at the beginning of a line -(with no spaces before). Unless you use the EQU directive, -the label is assigned the current value of the origin counter.
-Instructions and directives must be preceded with some whitespace. -Note that in xasm you can use instruction and directive -names as label names. For example
-nop -
defines a label called nop, whereas
-nop -
is a 6502 instruction.
-Full comment lines must start with a semicolon, a pipe or an asterisk, -with optional label definition and spaces before. Here are examples -of full comment lines:
-; this is a comment - * so it is -label | and this too --
Lines with instructions (and some directives) -may be repeated. A single line may be assembled several times, -for example:
-:4 asl @ -table :32*5 dta 5 --
In lines with instructions or directives, a comment starts immediately -after the instruction/directive has been successfully parsed. -That is, xasm does not require a special character to start a comment.
-lda foo ; this is a comment - sta bar so it is - tax #0 tax has no operand, therefore #0 starts this comment --
You may put two instructions in one line -so they share the operand. For example:
-eor:sta foo --
is equivalent to
-eor foo - sta foo --
Note that
-lda:tax #0 -
is allowed because #0 is treated as a comment for tax.
-Expressions are numbers combined with operators and brackets. -You should use square brackets, because parentheses are reserved -for 6502 indirect addressing.
-Numbers can be expressed as:
-Abbreviations of Atari hardware registers are provided to save you -the trouble of typing two extra characters (^4e vs $d40e) -and to ease porting software between Atari 8-bit computers and the Atari 5200 -console. These are very similar machines, one of the biggest differences is -the location of hardware registers.
-| Syntax | Chip | -Value in the Atari 8-bit computer mode (opt g-) |
-Value in the 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 |
An op-code is the single-byte op-code of the instruction inside braces. -The operand of the instruction is discarded and is necessary only -to recognize the addressing mode. The instruction should begin right after -the left brace and the right brace should immediately follow the operand -or the instruction. -You can skip the operand if the addressing mode -is fixed. Examples: -{lda #}, {jsr}, {bne}, {jmp ()}, -{sta a:,x}.
-You can use the line repeat counter (#) in the repeated lines. -It counts the iterations starting from zero. Examples:
-:3 dta # ; generates three bytes: 0, 1, 2. -line_lo :192 dta l(screen+40*#) -line_hi :192 dta h(screen+40*#) -dl :59 dta $4f,a(screen+40*#),0,$4f,a(screen+40*#),0 --
The follownig binary operators are supported:
-The following unary operators are supported:
-The operator precedence is following:
-| first | [] | -(brackets) |
| + - ~ < > | -(unary) | |
| * / % & << >> | -(binary) | |
| + - | ^ | -(binary) | |
| = == <> != < > <= >= | -(binary) | |
| ! | -(unary) | |
| && | -(binary) | |
| last | || | -(binary) |
Note that although the operators are similar to those 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 an expression, signed 32-bit arithmetic is used. -When range of 32 bits is exceeded, an 'Arithmetic overflow' error -occurs.
-five equ 5 -here equ * -
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 -
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 the ORG directive is executed). -
Starting with version 2.6.0, xasm supports code -that is relocated in the memory at runtime. Let's say you want your code -to be located on the zero page. You can't normally load it directly into this -place, so you load it at a different address and then move in your program. -org r: changes the address that it used for code generation -but not the address used for generating Atari executable headers. -Example:
-org $8000 - ldx #code_length-1 - mva:rpl code_loaded,x z:code_zpage,x- - jmp code_zpage - -code_loaded - org r:$30 -code_zpage - jmp * ; ... or something more sensible -code_length equ *-code_zpage --
Note that both * and label definitions use the counter used -for code generation. There is no direct access to the other counter, -because I think this is not useful. If you really need it, you can -always type something like:
-where_am_i equ *-code_zpage+code_loaded -
- 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 'lib/fileio' --Note: for portability, you should use only relative paths and slash -as the separator. This assures that your sources will compile under Windows -and Linux.
- end -
- ins 'file'[,offset[,length]] --The first byte in a file has the offset of zero.
- 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) --Example: -
run main -
ini showpic -
ert *>$c000 - ert len1>$ff||len2>$ff -
noscr equ 1 -widescr equ 1 - ift noscr - lda #0 - eli widescr - lda #$23 - els - lda #$22 - eif - sta $22f --The above example can be rewritten using the line repeating feature: -
noscr equ 1 -widescr equ 1 -:noscr lda #0 -:!noscr&&widescr lda #$23 -:!noscr&&!widescr lda #$22 - sta $22f -
Pseudo-commands are built-in macros.
-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 -
lda #40 - add:sta $80 - scc:inc $81 --In the above example the word-sized variable $80 is incremented by 40.
jne dest -is equivalent to: -
seq:jmp dest -
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 -
mv* source dest - mv* source+1 dest+1 --When source is an immediate value, an mw* #immed dest expands to: -
mv* <immed dest - mv* >immed dest+1 --When <immed equals >immed and immed -is not forward-referenced, xasm skips the second LD*: -
mv* <immed dest - st* dest+1 --If possible, MWX and MWY use increment/decrement -commands. For example, mwx #1 dest expands to: -
ldx #1 - stx dest - dex - stx dest+1 -
All addressing modes are entered in the standard 6502 convention except for -the accumulator addressing mode, which should be marked with -the @ character (as in Quick Assembler).
-There are two extra immediate addressing modes: -< and >, -which use the low/high byte of a 16-bit word constant. -They are for Quick Assembler compatibility. -You can use traditional #< and #>. -Note that lda >$ff+5 loads 1 (>$104), -while lda #>$ff+5 -loads 5 (0+5) to the accumulator, because the unary operator -> has a higher priority than the binary plus.
-You can explicitly choose absolute (a:) -and zero-page (z:) addressing modes.
-Examples:
-- nop - asl @ - lda >$1234 assembles to lda #$12 - lda $100,x - lda 0 zero-page (8-bit address) - lda a:0 absolute (16-bit address) - jmp ($0a) - lda ($80),y --
There are 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 --
xasm -i -d DEBUG=1 -l listing.lst source.asx -
ift 0 -foo equ 1 - ift foo - eif - eif --(bug found by Adrian Matoga)
ift 0 -:label nop - eif --reported Label not defined before error for the repeat count
ift 0 -label - eif --reported No ORG specified error for the label definition
Piotr Fusik (fox@scene.pl)
-xasm home page -(http://xasm.atari.org)
- -