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