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 For those instructions where the accumulator is the implied argument
164 (such as asl and lsr; inc and dec on R65C02; etc.), the idiom of
165 explicitly specifying the accumulator with a is unnecessary as the
166 proper form will be selected if there is no explicit argument. In fact,
167 for consistency with label handing, if there is a label named a, this
168 will actually generate code referencing that label as a memory location
169 and not the accumulator. Otherwise, the assembler will complain.
170 Labels and opcodes may take expressions as their arguments to allow
172 computed values, and may themselves reference other labels and/or the
173 program counter. An expression such as lab1+1 (which operates on the
174 current value of label lab1 and increments it by one) may use the fol‐
175 lowing operands, given from highest to lowest priority:
176 * multiplication (priority 10)
178 / integer division (priority 10)
180 + addition (priority 9)
182 - [22msubtraction (9)
184 << shift left (8)
186 >> shift right (8)
188 >= => greater than or equal to (7)
190 < greater than (7)
192 <= =< less than or equal to (7)
194 < less than (7)
196 = equal to (6)
198 <> >< does not equal (6)
200 & bitwise AND (5)
202 ^ bitwise XOR (4)
204 | bitwise OR (3)
206 && logical AND (2)
208 || logical OR (1)
210 Parentheses are valid. When redefining a label, combining arithmetic or
212 bitwise operators with the = (equals) operator such as += and so on are
213 valid, e.g.,
214 -redeflabel += (label12/4)
216 Normally, xa attempts to ascertain the value of the operand and (when
218 referring to a memory location) use zero page, 16-bit or (for 65816)
219 24-bit addressing where appropriate and where supported by the particu‐
220 lar opcode. This generates smaller and faster code, and is almost
221 always preferable.
222 Nevertheless, you can use these prefix operators to force a particular
224 rendering of the operand. Those that generate an eight bit result can
225 also be used in 8-bit addressing modes, such as immediate and zero
226 page.
227 < low byte of expression, e.g., lda #<vector
229 > high byte of expression
231 ! in situations where the expression could be understood as either
233 an absolute or zero page value, do not attempt to optimize to a
234 zero page argument for those opcodes that support it (i.e., keep
235 as 16 bit word)
236 @ render as 24-bit quantity for 65816 (must specify -w command-
238 line option). This is required to specify any 24-bit quantity!
239 ` force further optimization, even if the length of the instruc‐
241 tion cannot be reliably determined (see NOTES'N'BUGS)
242 Expressions can occur as arguments to opcodes or within the preproces‐
244 sor (see PREPROCESSOR for syntax). For example,
245 lda label2+1
247 takes the value at label2+1 (using our previous label's value, this
249 would be $d021), and will be assembled as $ad $21 $d0 to disk. Simi‐
250 larly,
251 lda #<label2
253 will take the lowest 8 bits of label2 (i.e., $20), and assign them to
255 the accumulator (assembling the instruction as $a9 $20 to disk).
256 Comments are specified with a semicolon (;), such as
258 ;this is a comment
260 They can also be specified in the C language style, using /* */ and //
262 which are understood at the PREPROCESSOR level (q.v.).
263 Normally, the colon (:) separates statements, such as
265 label4 lda #0:sta $d020
267 or
269 label2: lda #2
271 (note the use of a colon for specifying a label, similar to some other
273 assemblers, which xa also understands with or without the colon). This
274 also applies to semicolon comments, such that
275 ; a comment:lda #0
277 is understood as a comment followed by an opcode. To defeat this, use
279 the -M command line option to allow colons within comments. This does
280 not apply to /* */ and // comments, which are dealt with at the pre‐
281 processor level (q.v.).
282
285 Pseudo-ops are false opcodes used by the assembler to denote meta- or
286 inlined commands. Like most assemblers, xa has a rich set.
287 .byt value1,value2,value3,...
289 Specifies a string of bytes to be directly placed into the
290 assembled object. The arguments may be expressions. Any number
291 of bytes can be specified.
292 .asc "text1" ,"text2",...
294 Specifies a character string which will be inserted into the
295 assembled object. Strings are understood according to the cur‐
296 rently specified character set; for example, if ASCII is speci‐
297 fied, they will be rendered as ASCII, and if PETSCII is speci‐
298 fied, they will be translated into the equivalent Commodore
299 ASCII equivalent. Other non-standard ASCIIs such as ATASCII for
300 Atari computers should use the ASCII equivalent characters;
301 graphic and control characters should be specified explicitly
302 using .byt for the precise character you want. Note that when
303 specifying the argument of an opcode, .asc is not necessary; the
304 quoted character can simply be inserted (e.g., lda #"A" ), and
305 is also affected by the current character set. Any number of
306 character strings can be specified.
307 .byt and .asc are synonymous, so you can mix things such as .byt $43,
309 22, "a character string" and get the expected result. The string is
310 subject to the current character set, but the remaining bytes are
311 inserted wtihout modification.
312 .aasc "text1" ,"text2",...
314 Specifies a character string that is always rendered in true
315 ASCII regardless of the current character set. Like .asc, it is
316 synonymous with .byt.
317 .word value1,value2,value3...
319 Specifies a string of 16-bit words to be placed into the assem‐
320 bled object in 6502 little-endian format (that is, low-
321 byte/high-byte). The arguments may be expressions. Any number of
322 words can be specified.
323 .dsb length,fillbyte
325 Specifies a data block; a total of length repetitions of fill‐
326 byte will be inserted into the assembled object. For example,
327 .dsb 5,$10 will insert five bytes, each being 16 decimal, into
328 the object. The arguments may be expressions.
329 .bin offset,length,"filename"
331 Inlines a binary file without further interpretation specified
332 by filename from offset offset to length length. This allows
333 you to insert data such as a previously assembled object file or
334 an image or other binary data structure, inlined directly into
335 this file's object. If length is zero, then the length of file‐
336 name, minus the offset, is used instead. The arguments may be
337 expressions.
338 .( Opens a new block for scoping. Within a block, all labels
340 defined are local to that block and any sub-blocks, and go out
341 of scope as soon as the enclosing block is closed (i.e., lexi‐
342 cally scoped). All labels defined outside of the block are still
343 visible within it. To explicitly declare a global label within a
344 block, precede the label with + or precede it with & to declare
345 it within the previous level only (or globally if you are only
346 one level deep). Sixteen levels of scoping are permitted.
347 .) Closes a block.
349 .as .al .xs .xl
351 Only relevant in 65816 mode (with the -w option specified).
352 These pseudo-ops set what size accumulator and X/Y-register
353 should be used for future instructions; .as and .xs set 8-bit
354 operands for the accumulator and index registers, respectively,
355 and .al and .xl set 16-bit operands. These pseudo-ops on purpose
356 do not automatically issue sep and rep instructions to set the
357 specified width in the CPU; set the processor bits as you need,
358 or consider constructing a macro. .al and .xl generate errors
359 if -w is not specified.
360 The following pseudo-ops apply primarily to relocatable .o65 objects.
362 A full discussion of the relocatable format is beyond the scope of this
363 manpage, as it is currently a format in flux. Documentation on the pro‐
364 posed v1.2 format is in doc/fileformat.txt within the xa installation
365 directory.
366 .text .data .bss .zero
368 These pseudo-ops switch between the different segments, .text
369 being the actual code section, .data being the data segment,
370 .bss being uninitialized label space for allocation and .zero
371 being uninitialized zero page space for allocation. In .bss and
372 .zero, only labels are evaluated. These pseudo-ops are valid in
373 relative and absolute modes.
374 .align value
376 Aligns the current segment to a byte boundary (2, 4 or 256) as
377 specified by value (and places it in the header when relative
378 mode is enabled). Other values generate an error.
379 .fopt type,value1,value2,value3,...
381 Acts like .byt/.asc except that the values are embedded into the
382 object file as file options. The argument type is used to spec‐
383 ify the file option being referenced. A table of these options
384 is in the relocatable o65 file format description. The remainder
385 of the options are interpreted as values to insert. Any number
386 of values may be specified, and may also be strings.
387
390 xa implements a preprocessor very similar to that of the C-language
391 preprocessor cpp(1) and many oddiments apply to both. For example, as
392 in C, the use of /* */ for comment delimiters is also supported in xa,
393 and so are comments using the double slash //. The preprocessor also
394 supports continuation lines, i.e., lines ending with a backslash (\);
395 the following line is then appended to it as if there were no dividing
396 newline. This too is handled at the preprocessor level.
397 For reasons of memory and complexity, the full breadth of the cpp(1)
399 syntax is not fully supported. In particular, macro definitions may not
400 be forward-defined (i.e., a macro definition can only reference a pre‐
401 viously defined macro definition), except for macro functions, where
402 recursive evaluation is supported; e.g., to #define WW AA , AA must
403 have already been defined. Certain other directives are not supported,
404 nor are most standard pre-defined macros, and there are other limits on
405 evaluation and line length. Because the maintainers of xa recognize
406 that some files will require more complicated preparsing than the
407 built-in preprocessor can supply, the preprocessor will accept
408 cpp(1)-style line/filename/flags output. When these lines are seen in
409 the input file, xa will treat them as cc would, except that flags are
410 ignored. xa does not accept files on standard input for parsing rea‐
411 sons, so you should dump your cpp(1) output to an intermediate tempo‐
412 rary file, such as
413 cc -E test.s > test.xa
415 xa test.xa
416 No special arguments need to be passed to xa; the presence of cpp(1)
418 output is detected automatically.
419 Note that passing your file through cpp(1) may interfere with xa's own
421 preprocessor directives. In this case, to mask directives from cpp(1),
422 use the -p option to specify an alternative character instead of #,
423 such as the tilde (e.g., -p'~' ). With this option and argument speci‐
424 fied, then instead of #include, for example, you can also use ~include,
425 in addition to #include (which will also still be accepted by the xa
426 preprocessor, assuming any survive cpp(1)). Any character can be used,
427 although frankly pathologic choices may lead to amusing and frustrating
428 glitches during parsing. You can also use this option to defer pre‐
429 processor directives that cpp(1) may interpret too early until the file
430 actually gets to xa itself for processing.
431 The following preprocessor directives are supported.
433 #include "filename"
436 Inserts the contents of file filename at this position. If the
437 file is not found, it is searched using paths specified by the
438 -I command line option or the environment variable XAINPUT
439 (q.v.). When inserted, the file will also be parsed for pre‐
440 processor directives.
441 #echo comment
443 Inserts comment comment into the errorlog file, specified with
444 the -e command line option.
445 #print expression
447 Computes the value of expression expression and prints it into
448 the errorlog file.
449 #define DEFINE text
451 Equates macro DEFINE with text text such that wherever DEFINE
452 appears in the assembly source, text is substituted in its place
453 (just like cpp(1) would do). In addition, #define can specify
454 macro functions like cpp(1) such that a directive like #define
455 mult(a,b) ((a)*(b)) would generate the expected result wherever
456 an expression of the form mult(a,b) appears in the source. This
457 can also be specified on the command line with the -D option.
458 The arguments of a macro function may be recursively evaluated,
459 unlike other #defines; the preprocessor will attempt to re-eval‐
460 uate any argument refencing another preprocessor definition up
461 to ten times before complaining.
462 The following directives are conditionals. If the conditional is not
464 satisfied, then the source code between the directive and its terminat‐
465 ing #endif are expunged and not assembled. Up to fifteen levels of
466 nesting are supported.
467 #endif Closes a conditional block.
469 #else Implements alternate path for a conditional block.
471 #ifdef DEFINE
473 True only if macro DEFINE is defined.
474 #ifndef DEFINE
476 The opposite; true only if macro DEFINE has not been previously
477 defined.
478 #if expression
480 True if expression expression evaluates to non-zero. expression
481 may reference other macros.
482 #iflused label
484 True if label label has been used (but not necessarily instanti‐
485 ated with a value). This works on labels, not macros!
486 #ifldef label
488 True if label label is defined and assigned with a value. This
489 works on labels, not macros!
490 Unclosed conditional blocks at the end of included files generate warn‐
492 ings; unclosed conditional blocks at the end of assembly generate an
493 error.
494 #iflused and #ifldef are useful for building up a library based on
496 labels. For example, you might use something like this in your
497 library's code:
498 #iflused label
500 #ifldef label
501 #echo label already defined, library function label cannot be
502 inserted
503 #else
504 label /* your code */
505 #endif
506 #endif
507
510 xa utilises the following environment variables, if they exist:
511 XAINPUT
514 Include file path; components should be separated by `,'.
515 XAOUTPUT
517 Output file path.
518
521 The R65C02 instructions ina (often rendered inc a) and dea (dec a) must
522 be rendered as bare inc and dec instructions respectively.
523 Forward-defined labels -- that is, labels that are defined after the
525 current instruction is processed -- cannot be optimized into zero page
526 instructions even if the label does end up being defined as a zero page
527 location, because the assembler does not know the value of the label in
528 advance during the first pass when the length of an instruction is com‐
529 puted. On the second pass, a warning will be issued when an instruction
530 that could have been optimized can't be because of this limitation.
531 (Obviously, this does not apply to branching or jumping instructions
532 because they're not optimizable anyhow, and those instructions that can
533 only take an 8-bit parameter will always be casted to an 8-bit quan‐
534 tity.) If the label cannot otherwise be defined ahead of the instruc‐
535 tion, the backtick prefix ` may be used to force further optimization
536 no matter where the label is defined as long as the instruction sup‐
537 ports it. Indiscriminately forcing the issue can be fraught with
538 peril, however, and is not recommended; to discourage this, the assem‐
539 bler will complain about its use in addressing mode situations where no
540 ambiguity exists, such as indirect indexed, branching and so on.
541 Also, as a further consequence of the way optimization is managed, we
543 repeat that all 24-bit quantities and labels that reference a 24-bit
544 quantity in 65816 mode, anteriorly declared or otherwise, MUST be
545 prepended with the @ prefix. Otherwise, the assembler will attempt to
546 optimize to 16 bits, which may be undesirable.
547
550 file65(1), ldo65(1), printcbm(1), reloc65(1), uncpk(1), dxa(1)
551
554 This manual page was written by David Weinehall <tao@acc.umu.se>, Andre
555 Fachat <fachat@web.de> and Cameron Kaiser <ckaiser@floodgap.com>.
556 Original xa package (C)1989-1997 Andre Fachat. Additional changes
557 (C)1989-2009 Andre Fachat, Jolse Maginnis, David Weinehall, Cameron
558 Kaiser. The official maintainer is Cameron Kaiser.
559
562 http://www.floodgap.com/retrotech/xa/
563 7 February 2009 XA(1)