`xa` (`xa65`)

xa is Andre Fachat's open-source 6502 cross assembler. I, Cameron Kaiser (ckaiser@floodgap.com), am the current maintainer, and bug reports and questions should now go to me.

xa is Copyright © 1989-2024, André Fachat, Jolse Maginnis, David Weinehall and Cameron Kaiser. All rights reserved. Additional contributors: Fabien Nuñez, Mikkel Holm Olsen, Adam Sampson, Alessandro Gatti, Simon Rowe, Dan Horák, Frederic Cambus, Sam Falvo, Stephen Kitt, Bas Wassink, Sergei Trofimovich, Tom Hargreaves. xa is distributed under the GNU Public License v2. The current maintainer is Cameron Kaiser.

For a complete list of available files and distributions, check the dists/ directory.

For other Floodgap-maintained packages, see the Floodgap Software listing.

What is `xa`?

xa is a high-speed, two-pass portable cross-assembler. It understands mnemonics and generates code for NMOS 6502s (such as 6502A, 6504, 6507, 6510, 7501, 8500, 8501, 8502 ...), CMOS 6502s (65C02 and Rockwell R65C02) and the 65816.

Key amongst its features:

C-like preprocessor (and understands cpp for additional feature support)
rich expression syntax and pseudo-op vocabulary
multiple character sets
binary linking
supports o65 relocatable objects with a full linker and relocation suite, as well as "bare" plain binary object files
block structure for label scoping

xa's eventual companion disassembler is dxa, a moderately hacked-up version of Marko Mäkelä's d65 disassembler. This is still alpha and is available as a separate distribution until it is stabilized enough to be part of the xa suite.

Version 2.4.1 (5 March 2024)

2.4.1 is a bug fix and small feature update for 2.4.0. 2.4.0 is a significant update of the code base with many new features. However, because this is more than just a point release, there are potentially incompatibilities with edge cases in 2.3 and earlier versions, and features that were declared deprecated in 2.3 have been removed.

xa-2.4.1.tar.gz

xa should compile out of the box on just about any Unix or Unixy thing, and will probably compile on other systems that support ANSI C as well. Please see the README.1st file for more detailed instructions. It is tested and validated on AIX (gcc), Linux/ppc64le (gcc and clang), Mac OS X (gcc on PowerPC, and clang on Intel x86_64 and Apple silicon) and NetBSD/macppc and NetBSD/mac68k (gcc).

What's new in 2.4.1

Allow colon-based unnamed labels to be used separately of CA65 mode (such as with 65816) with -a. Implies -XMASM.
Restore ^ syntax for generating control sequences (e.g., "^m^j" evaluates as 0d 0a) with -k.
Fix a bug using cheap local labels in expressions.
Properly tag and match CPU types in o65 objects during relocation and linking.
Fix a bug with .align when aligning segments.
Better validation of arguments to indexed opcodes.
Testsuite expanded.

What's new in 2.4.0

In case you missed it. Too much to completely enumerate, but here's the hits.

Listing feature (-P, -F) in plain text or HTML, along with .listbytes to control how hex bytes get listed in the output.
Add -E commandline option to not stop after 20 errors, but show all of them.
Introduce -X compatibility set command line option to distinguish between MASM and CA65 compatibility options; also adds C option for 0x and 0 to specify hex or octal. As a result, -M is now deprecated, and colons in comments may become the default in a future version.
Implement CA65 "cheap local labels", ":=" label definitions, and various pseudo-opcodes (.include, .import, .importzp, .zeropage, .proc (anonymous only), .endproc, .code, .org, .reloc).
-U option to allow all undefined labels in relocating mode; this allows exporting them to an .o65 file and link at a later time (or specify one at a time with -L).
Globals may also be specified manually with -g.
#error allows preprocessor-level assertions.
.assert allows assembler-level assertions.
Better fix for segfault with smaller arity macro issue.
Main Makefile fixes.
Fixed parallel make in tests, incorporating a patch from Sergei Trofimovich.
Added a test case that failed in 2.3.14 from Tom Hargreaves.
Some 2.3.x features still allowed with -XXA23, which is obviously deprecated.
The quote escape character is now the \ (backslash), except if -XXA23.
Recursive /* */ comments are no longer allowed, except if -XXA23.
XA_MAJOR and XA_MINOR predefined macros, except if -XXA23.
Testsuite greatly expanded.
The old loader/ testsuite and doc/ archive are now in attic/, which is the repository for old unsupported components. It may be purged in a future version.
-M is now deprecated (use -XMASM), just in case you forgot.
printcbm(1) is now deprecated (use VICE petcat, it does a lot more).
Previously deprecated options (16-bit mvn/mvp argument, -S, -x) finally removed. If you need this support, you must use 2.3.x.

Documentation

Documentation is now in man format since 2.3.0. You can read them here, converted with man2html:

For those using older distributions, refer to the previous xa HTML documentation.

History

I'll just let Andre tell it:

"I developed the first version of xa on my old Atari ST to build programms for my selfbuilt computer CS/A65. After my Atari broke I ported it to Linux (ported? It compiled right out of the box!) and when I had to develop a programm for a friend of mine, I compiled it on an Amiga without errors. Until the beginning of 1992 I made more improvements, until it came to version 2.0.7. Since then I only very occasionally worked on it, up to version 2.0.7d. When I decided to push my selfbuilt OS to a new level in 1996, I needed more important improvements, like o65 object format and a linker and all that."

`dxa`

Starting with 2.3.0, xa is now officially accompanied by dxa, its companion disassembler. dxa is a rudely hacked version of Marko Mäkelä's d65 package, with some extra features and altered output to allow "perfect" disassembly (which is to say, you can take an arbitrary object, run it through dxa, take what it spits out, run it back through xa, and get the binary you started with). It also has features for intelligently labeling code and data sections and multiple output formats, and can understand undocumented and CMOS opcodes (65816 not yet).

Because dxa is new and not well tested, I have not included it as part of the standard xa distribution and it is offered here separately. Please consider it to be alpha software only and expect bugs. Refer to the readme for instructions on installation. dxa, like d65, is distributed under GPL v2.

Version 0.1.5 (25 March 2022)

New in this version is a formal, if small, test suite for the very first time (make test). This disassembles a set of binary test vectors, reassembles them (with xa, natch), and checks that the output matches the original binaries. You need xa installed. If make test fails, make sure your xa is current before reporting a bug. dxa is now validated on all the platforms xa is.

There are also many fixes in this version, including properly getting the very last byte for files that load all the way to $ffff and correctly (IMNSHO) truncating files that load beyond (thanks Malte), fixes for bugs with clang-built dxa generating incorrect code, fixes for an issue with the C preprocessor, and more flexible BASIC header detection. Note that clang-built dxa does behave differently than gcc-built dxa and more research is needed (currently the only guarantee is that both will generate an assembly file which will assemble to identical binaries). dxa is based on d65 0.2.1.