1XA(1) General Commands Manual XA(1)
2
6 xa - 6502/R65C02/65816 cross-assembler
7
10 xa [OPTION]... FILE
11
14 xa is a multi-pass cross-assembler for the 8-bit processors in the 6502
15 series (such as the 6502, 65C02, 6504, 6507, 6510, 7501, 8500, 8501 and
16 8502), the Rockwell R65C02, and the 16-bit 65816 processor. For a
17 description of syntax, see ASSEMBLER SYNTAX further in this manual
18 page.
19
22 -v Verbose output.
23 -x Use old filename behaviour (overrides -o, -e and -l). This
25 option is now deprecated.
26 -C No CMOS opcodes (default is to allow R65C02 opcodes).
28 -W No 65816 opcodes (default).
30 -w Allow 65816 opcodes.
32 -B Show lines with block open/close (see PSEUDO-OPS).
34 -c Produce o65 object files instead of executable files (no linking
36 performed); files may contain undefined references.
37 -o filename
39 Set output filename. The default is a.o65; use the special file‐
40 name - to output to standard output.
41 -e filename
43 Set errorlog filename, default is none.
44 -l filename
46 Set labellist filename, default is none. This is the symbol ta‐
47 ble and can be used by disassemblers such as dxa(1) to recon‐
48 struct source.
49 -r Add cross-reference list to labellist (requires -l).
51 -M Allow colons to appear in comments; for MASM compatibility. This
53 does not affect colon interpretation elsewhere.
54 -R Start assembler in relocating mode.
56 -Llabel
58 Defines label as an absolute (but undefined) label even when
59 linking.
60 -b? addr
62 Set segment base for segment ? to address addr. ? should be
63 t, d, b or z for text, data, bss or zero segments, respectively.
64 -A addr
66 Make text segment start at an address such that when the file
67 starts at address addr, relocation is not necessary. Overrides
68 -bt; other segments still have to be taken care of with -b.
69 -G Suppress list of exported globals.
72 -DDEF=TEXT
74 Define a preprocessor macro on the command line (see PREPROCES‐
75 SOR).
76 -I dir Add directory dir to the include path (before XAINPUT; see ENVI‐
78 RONMENT).
79 -O charset
81 Define the output charset for character strings. Currently sup‐
82 ported are ASCII (default), PETSCII (Commodore ASCII), PETSCREEN
83 (Commodore screen codes) and HIGH (set high bit on all charac‐
84 ters).
85 -p? Set the alternative preprocessor character to ?. This is useful
87 when you wish to use cpp(1) and the built-in preprocessor at the
88 same time (see PREPROCESSOR). Characters may need to be quoted
89 for your shell (example: -p'~' ).
90 --help Show summary of options.
92 --version
94 Show version of program.
95
98 An introduction to 6502 assembly language programming and mnemonics is
99 beyond the scope of this manual page. We invite you to investigate any
100 number of the excellent books on the subject; one useful title is
101 "Machine Language For Beginners" by Richard Mansfield (COMPUTE!), cov‐
102 ering the Atari, Commodore and Apple 8-bit systems, and is widely
103 available on the used market.
104 xa supports both the standard NMOS 6502 opcodes as well as the Rockwell
106 CMOS opcodes used in the 65C02 (R65C02). With the -w option, xa will
107 also accept opcodes for the 65816. NMOS 6502 undocumented opcodes are
108 intentionally not supported, and should be entered manually using the
109 .byte pseudo-op (see PSEUDO-OPS). Due to conflicts between the R65C02
110 and 65816 instruction sets and undocumented instructions on the NMOS
111 6502, their use is discouraged.
112 In general, xa accepts the more-or-less standard 6502 assembler format
114 as popularised by MASM and TurboAssembler. Values and addresses can be
115 expressed either as literals, or as expressions; to wit,
116 123 decimal value
118 $234 hexadecimal value
120 &123 octal
122 %010110 binary
124 * current value of the program counter
126 The ASCII value of any quoted character is inserted directly into the
128 program text (example: "A" inserts the byte "A" into the output
129 stream); see also the PSEUDO-OPS section. This is affected by the cur‐
130 rently selected character set, if any.
131 Labels define locations within the program text, just as in other
133 multi-pass assemblers. A label is defined by anything that is not an
134 opcode; for example, a line such as
135 label1 lda #0
137 defines label1 to be the current location of the program counter (thus
139 the address of the LDA opcode). A label can be explicitly defined by
140 assigning it the value of an expression, such as
141 label2 = $d000
143 which defines label2 to be the address $d000, namely, the start of the
145 VIC-II register block on Commodore 64 computers. The program counter *
146 is considered to be a special kind of label, and can be assigned to
147 with statements such as
148 * = $c000
150 which sets the program counter to decimal location 49152. With the
152 exception of the program counter, labels cannot be assigned multiple
153 times. To explicitly declare redefinition of a label, place a - (dash)
154 before it, e.g.,
155 -label2 = $d020
157 which sets label2 to the Commodore 64 border colour register. The scope
159 of a label is affected by the block it resides within (see PSEUDO-OPS
160 for block instructions). A label may also be hard-specified with the -L
161 command line option.
162 Redefining a label does not change previously assembled code that used
164 the earlier value. Therefore, because the program counter is a special
165 type of label, changing the program counter to a lower value does not
166 reorder code assembled previously and changing it to a higher value
167 does not issue padding to put subsequent code at the new location. This
168 is intentional behaviour to facilitate generating relocatable and posi‐
169 tion-independent code, but can differ from other assemblers which use
170 this behaviour for linking. However, it is possible to use pseudo-ops
171 to simulate other assemblers' behaviour and use xa as a linker; see
172 PSEUDO-OPS and LINKING.
173 For those instructions where the accumulator is the implied argument
175 (such as asl and lsr; inc and dec on R65C02; etc.), the idiom of
176 explicitly specifying the accumulator with a is unnecessary as the
177 proper form will be selected if there is no explicit argument. In fact,
178 for consistency with label handling, if there is a label named a, this
179 will actually generate code referencing that label as a memory location
180 and not the accumulator. Otherwise, the assembler will complain.
181 Labels and opcodes may take expressions as their arguments to allow
183 computed values, and may themselves reference other labels and/or the
184 program counter. An expression such as lab1+1 (which operates on the
185 current value of label lab1 and increments it by one) may use the fol‐
186 lowing operands, given from highest to lowest priority:
187 * multiplication (priority 10)
189 / integer division (priority 10)
191 + addition (priority 9)
193 - [22msubtraction (9)
195 << shift left (8)
197 >> shift right (8)
199 >= => greater than or equal to (7)
201 < greater than (7)
203 <= =< less than or equal to (7)
205 < less than (7)
207 = equal to (6)
209 <> >< does not equal (6)
211 & bitwise AND (5)
213 ^ bitwise XOR (4)
215 | bitwise OR (3)
217 && logical AND (2)
219 || logical OR (1)
221 Parentheses are valid. When redefining a label, combining arithmetic or
223 bitwise operators with the = (equals) operator such as += and so on are
224 valid, e.g.,
225 -redeflabel += (label12/4)
227 Normally, xa attempts to ascertain the value of the operand and (when
229 referring to a memory location) use zero page, 16-bit or (for 65816)
230 24-bit addressing where appropriate and where supported by the particu‐
231 lar opcode. This generates smaller and faster code, and is almost
232 always preferable.
233 Nevertheless, you can use these prefix operators to force a particular
235 rendering of the operand. Those that generate an eight bit result can
236 also be used in 8-bit addressing modes, such as immediate and zero
237 page.
238 < low byte of expression, e.g., lda #<vector
240 > high byte of expression
242 ! in situations where the expression could be understood as either
244 an absolute or zero page value, do not attempt to optimize to a
245 zero page argument for those opcodes that support it (i.e., keep
246 as 16 bit word)
247 @ render as 24-bit quantity for 65816 (must specify -w command-
249 line option). This is required to specify any 24-bit quantity!
250 ` force further optimization, even if the length of the instruc‐
252 tion cannot be reliably determined (see NOTES'N'BUGS)
253 Expressions can occur as arguments to opcodes or within the preproces‐
255 sor (see PREPROCESSOR for syntax). For example,
256 lda label2+1
258 takes the value at label2+1 (using our previous label's value, this
260 would be $d021), and will be assembled as $ad $21 $d0 to disk. Simi‐
261 larly,
262 lda #<label2
264 will take the lowest 8 bits of label2 (i.e., $20), and assign them to
266 the accumulator (assembling the instruction as $a9 $20 to disk).
267 Comments are specified with a semicolon (;), such as
269 ;this is a comment
271 They can also be specified in the C language style, using /* */ and //
273 which are understood at the PREPROCESSOR level (q.v.).
274 Normally, the colon (:) separates statements, such as
276 label4 lda #0:sta $d020
278 or
280 label2: lda #2
282 (note the use of a colon for specifying a label, similar to some other
284 assemblers, which xa also understands with or without the colon). This
285 also applies to semicolon comments, such that
286 ; a comment:lda #0
288 is understood as a comment followed by an opcode. To defeat this, use
290 the -M command line option to allow colons within comments. This does
291 not apply to /* */ and // comments, which are dealt with at the pre‐
292 processor level (q.v.).
293
296 Pseudo-ops are false opcodes used by the assembler to denote meta- or
297 inlined commands. Like most assemblers, xa has a rich set.
298 .byt value1,value2,value3,...
300 Specifies a string of bytes to be directly placed into the
301 assembled object. The arguments may be expressions. Any number
302 of bytes can be specified.
303 .asc "text1" ,"text2",...
305 Specifies a character string which will be inserted into the
306 assembled object. Strings are understood according to the cur‐
307 rently specified character set; for example, if ASCII is speci‐
308 fied, they will be rendered as ASCII, and if PETSCII is speci‐
309 fied, they will be translated into the equivalent Commodore
310 ASCII equivalent. Other non-standard ASCIIs such as ATASCII for
311 Atari computers should use the ASCII equivalent characters;
312 graphic and control characters should be specified explicitly
313 using .byt for the precise character you want. Note that when
314 specifying the argument of an opcode, .asc is not necessary; the
315 quoted character can simply be inserted (e.g., lda #"A" ), and
316 is also affected by the current character set. Any number of
317 character strings can be specified.
318 .byt and .asc are synonymous, so you can mix things such as .byt $43,
320 22, "a character string" and get the expected result. The string is
321 subject to the current character set, but the remaining bytes are
322 inserted wtihout modification.
323 .aasc "text1" ,"text2",...
325 Specifies a character string that is always rendered in true
326 ASCII regardless of the current character set. Like .asc, it is
327 synonymous with .byt.
328 .word value1,value2,value3...
330 Specifies a string of 16-bit words to be placed into the assem‐
331 bled object in 6502 little-endian format (that is, low-
332 byte/high-byte). The arguments may be expressions. Any number of
333 words can be specified.
334 .dsb length,fillbyte
336 Specifies a data block; a total of length repetitions of fill‐
337 byte will be inserted into the assembled object. For example,
338 .dsb 5,$10 will insert five bytes, each being 16 decimal, into
339 the object. The arguments may be expressions. See LINKING for
340 how to use this pseudo-op to link multiple objects.
341 .bin offset,length,"filename"
343 Inlines a binary file without further interpretation specified
344 by filename from offset offset to length length. This allows
345 you to insert data such as a previously assembled object file or
346 an image or other binary data structure, inlined directly into
347 this file's object. If length is zero, then the length of file‐
348 name, minus the offset, is used instead. The arguments may be
349 expressions. See LINKING for how to use this pseudo-op to link
350 multiple objects.
351 .( Opens a new block for scoping. Within a block, all labels
353 defined are local to that block and any sub-blocks, and go out
354 of scope as soon as the enclosing block is closed (i.e., lexi‐
355 cally scoped). All labels defined outside of the block are still
356 visible within it. To explicitly declare a global label within a
357 block, precede the label with + or precede it with & to declare
358 it within the previous level only (or globally if you are only
359 one level deep). Sixteen levels of scoping are permitted.
360 .) Closes a block.
362 .as .al .xs .xl
364 Only relevant in 65816 mode (with the -w option specified).
365 These pseudo-ops set what size accumulator and X/Y-register
366 should be used for future instructions; .as and .xs set 8-bit
367 operands for the accumulator and index registers, respectively,
368 and .al and .xl set 16-bit operands. These pseudo-ops on purpose
369 do not automatically issue sep and rep instructions to set the
370 specified width in the CPU; set the processor bits as you need,
371 or consider constructing a macro. .al and .xl generate errors
372 if -w is not specified.
373 The following pseudo-ops apply primarily to relocatable .o65 objects.
375 A full discussion of the relocatable format is beyond the scope of this
376 manpage, as it is currently a format in flux. Documentation on the pro‐
377 posed v1.2 format is in doc/fileformat.txt within the xa installation
378 directory.
379 .text .data .bss .zero
381 These pseudo-ops switch between the different segments, .text
382 being the actual code section, .data being the data segment,
383 .bss being uninitialized label space for allocation and .zero
384 being uninitialized zero page space for allocation. In .bss and
385 .zero, only labels are evaluated. These pseudo-ops are valid in
386 relative and absolute modes.
387 .align value
389 Aligns the current segment to a byte boundary (2, 4 or 256) as
390 specified by value (and places it in the header when relative
391 mode is enabled). Other values generate an error.
392 .fopt type,value1,value2,value3,...
394 Acts like .byt/.asc except that the values are embedded into the
395 object file as file options. The argument type is used to spec‐
396 ify the file option being referenced. A table of these options
397 is in the relocatable o65 file format description. The remainder
398 of the options are interpreted as values to insert. Any number
399 of values may be specified, and may also be strings.
400
403 xa implements a preprocessor very similar to that of the C-language
404 preprocessor cpp(1) and many oddiments apply to both. For example, as
405 in C, the use of /* */ for comment delimiters is also supported in xa,
406 and so are comments using the double slash //. The preprocessor also
407 supports continuation lines, i.e., lines ending with a backslash (\);
408 the following line is then appended to it as if there were no dividing
409 newline. This too is handled at the preprocessor level.
410 For reasons of memory and complexity, the full breadth of the cpp(1)
412 syntax is not fully supported. In particular, macro definitions may not
413 be forward-defined (i.e., a macro definition can only reference a pre‐
414 viously defined macro definition), except for macro functions, where
415 recursive evaluation is supported; e.g., to #define WW AA , AA must
416 have already been defined. Certain other directives are not supported,
417 nor are most standard pre-defined macros, and there are other limits on
418 evaluation and line length. Because the maintainers of xa recognize
419 that some files will require more complicated preparsing than the
420 built-in preprocessor can supply, the preprocessor will accept
421 cpp(1)-style line/filename/flags output. When these lines are seen in
422 the input file, xa will treat them as cc would, except that flags are
423 ignored. xa does not accept files on standard input for parsing rea‐
424 sons, so you should dump your cpp(1) output to an intermediate tempo‐
425 rary file, such as
426 cc -E test.s > test.xa
428 xa test.xa
429 No special arguments need to be passed to xa; the presence of cpp(1)
431 output is detected automatically.
432 Note that passing your file through cpp(1) may interfere with xa's own
434 preprocessor directives. In this case, to mask directives from cpp(1),
435 use the -p option to specify an alternative character instead of #,
436 such as the tilde (e.g., -p'~' ). With this option and argument speci‐
437 fied, then instead of #include, for example, you can also use ~include,
438 in addition to #include (which will also still be accepted by the xa
439 preprocessor, assuming any survive cpp(1)). Any character can be used,
440 although frankly pathologic choices may lead to amusing and frustrating
441 glitches during parsing. You can also use this option to defer pre‐
442 processor directives that cpp(1) may interpret too early until the file
443 actually gets to xa itself for processing.
444 The following preprocessor directives are supported.
446 #include "filename"
449 Inserts the contents of file filename at this position. If the
450 file is not found, it is searched using paths specified by the
451 -I command line option or the environment variable XAINPUT
452 (q.v.). When inserted, the file will also be parsed for pre‐
453 processor directives.
454 #echo comment
456 Inserts comment comment into the errorlog file, specified with
457 the -e command line option.
458 #print expression
460 Computes the value of expression expression and prints it into
461 the errorlog file.
462 #define DEFINE text
464 Equates macro DEFINE with text text such that wherever DEFINE
465 appears in the assembly source, text is substituted in its place
466 (just like cpp(1) would do). In addition, #define can specify
467 macro functions like cpp(1) such that a directive like #define
468 mult(a,b) ((a)*(b)) would generate the expected result wherever
469 an expression of the form mult(a,b) appears in the source. This
470 can also be specified on the command line with the -D option.
471 The arguments of a macro function may be recursively evaluated,
472 unlike other #defines; the preprocessor will attempt to re-eval‐
473 uate any argument refencing another preprocessor definition up
474 to ten times before complaining.
475 The following directives are conditionals. If the conditional is not
477 satisfied, then the source code between the directive and its terminat‐
478 ing #endif are expunged and not assembled. Up to fifteen levels of
479 nesting are supported.
480 #endif Closes a conditional block.
482 #else Implements alternate path for a conditional block.
484 #ifdef DEFINE
486 True only if macro DEFINE is defined.
487 #ifndef DEFINE
489 The opposite; true only if macro DEFINE has not been previously
490 defined.
491 #if expression
493 True if expression expression evaluates to non-zero. expression
494 may reference other macros.
495 #iflused label
497 True if label label has been used (but not necessarily instanti‐
498 ated with a value). This works on labels, not macros!
499 #ifldef label
501 True if label label is defined and assigned with a value. This
502 works on labels, not macros!
503 Unclosed conditional blocks at the end of included files generate warn‐
505 ings; unclosed conditional blocks at the end of assembly generate an
506 error.
507 #iflused and #ifldef are useful for building up a library based on
509 labels. For example, you might use something like this in your
510 library's code:
511 #iflused label
513 #ifldef label
514 #echo label already defined, library function label cannot be
515 inserted
516 #else
517 label /* your code */
518 #endif
519 #endif
520
523 xa is oriented towards generating sequential binaries. Code is strictly
524 emitted in order even if the program counter is set to a lower location
525 than previously assembled code, and padding is not automatically emit‐
526 ted if the program counter is set to a higher location. Changing the
527 program location only changes new labels for code that is subsequently
528 emitted; previous emitted code remains unchanged. Fortunately, for many
529 object files these conventions have no effect on their generation.
530 However, some applications may require generating an object file built
532 from several previously generated components, and/or submodules which
533 may need to be present at specific memory locations. With a minor
534 amount of additional specification, it is possible to use xa for this
535 purpose as well.
536 The first means of doing so uses the o65 format to make relocatable
538 objects that in turn can be linked by ldo65(1) (q.v.).
539 The second means involves either assembled code, or insertion of previ‐
541 ously built object or data files with .bin, using .dsb pseudo-ops with
542 computed expression arguments to insert any necessary padding between
543 them, in the sequential order they are to reside in memory. Consider
544 this example:
545 .word $1000
547 * = $1000
548 ; this is your code at $1000
550 part1 rts
551 ; this label marks the end of code
552 endofpart1
553 ; DON'T PUT A NEW .word HERE!
555 * = $2000
556 .dsb (*-endofpart1), 0
557 ; yes, set it again
558 * = $2000
559 ; this is your code at $2000
561 part2 rts
562 This example, written for Commodore microcomputers using a 16-bit
564 starting address, has two "modules" in it: one block of code at $1000
565 (4096), indicated by the code between labels part1 and endofpart1, and
566 a second block at $2000 (8192) starting at label part2.
567 The padding is computed by the .dsb pseudo-op between the two modules.
569 Note that the program counter is set to the new address and then a com‐
570 puted expression inserts the proper number of fill bytes from the end
571 of the assembled code in part 1 up to the new program counter address.
572 Since this itself advances the program counter, the program counter is
573 reset again, and assembly continues.
574 When the object this source file generates is loaded, there will be an
576 rts instruction at address 4096 and another at address 8192, with null
577 bytes between them.
578 Should one of these areas need to contain a pre-built file, instead of
580 assembly code, simply use a .bin pseudo-op to load whatever portions of
581 the file are required into the output. The computation of addresses and
582 number of necessary fill bytes is done in the same fashion.
583 Although this example used the program counter itself to compute the
585 difference between addresses, you can use any label for this purpose,
586 keeping in mind that only the program counter determines where relative
587 addresses within assembled code are resolved.
588
591 xa utilises the following environment variables, if they exist:
592 XAINPUT
595 Include file path; components should be separated by `,'.
596 XAOUTPUT
598 Output file path.
599
602 The R65C02 instructions ina (often rendered inc a) and dea (dec a) must
603 be rendered as bare inc and dec instructions respectively.
604 The 65816 instructions mvn and mvp use two eight bit parameters, the
606 only instructions in the entire instruction set to do so. Older ver‐
607 sions of xa took a single 16-bit absolute value. Since 2.3.7, the stan‐
608 dard syntax is now accepted and the old syntax is deprecated (a warning
609 will be generated).
610 Forward-defined labels -- that is, labels that are defined after the
612 current instruction is processed -- cannot be optimized into zero page
613 instructions even if the label does end up being defined as a zero page
614 location, because the assembler does not know the value of the label in
615 advance during the first pass when the length of an instruction is com‐
616 puted. On the second pass, a warning will be issued when an instruction
617 that could have been optimized can't be because of this limitation.
618 (Obviously, this does not apply to branching or jumping instructions
619 because they're not optimizable anyhow, and those instructions that can
620 only take an 8-bit parameter will always be casted to an 8-bit quan‐
621 tity.) If the label cannot otherwise be defined ahead of the instruc‐
622 tion, the backtick prefix ` may be used to force further optimization
623 no matter where the label is defined as long as the instruction sup‐
624 ports it. Indiscriminately forcing the issue can be fraught with
625 peril, however, and is not recommended; to discourage this, the assem‐
626 bler will complain about its use in addressing mode situations where no
627 ambiguity exists, such as indirect indexed, branching and so on.
628 Also, as a further consequence of the way optimization is managed, we
630 repeat that all 24-bit quantities and labels that reference a 24-bit
631 quantity in 65816 mode, anteriorly declared or otherwise, MUST be
632 prepended with the @ prefix. Otherwise, the assembler will attempt to
633 optimize to 16 bits, which may be undesirable.
634
637 file65(1), ldo65(1), printcbm(1), reloc65(1), uncpk(1), dxa(1)
638
641 This manual page was written by David Weinehall <tao@acc.umu.se>, Andre
642 Fachat <fachat@web.de> and Cameron Kaiser <ckaiser@floodgap.com>.
643 Original xa package (C)1989-1997 Andre Fachat. Additional changes
644 (C)1989-2019 Andre Fachat, Jolse Maginnis, David Weinehall, Cameron
645 Kaiser. The official maintainer is Cameron Kaiser.
646
649 Yay us?
650
653 http://www.floodgap.com/retrotech/xa/
654 31 January 2019 XA(1)