1asm6809(1) General Commands Manual asm6809(1)
2
6 asm6809—6809 cross-assembler
7
9 asm6809 [OPTION]… [SOURCE-FILE]…
10
12 asm6809 is a portable macro cross assembler targeting the Motorola 6809
13 and Hitachi 6309 processors. These processors are most commonly
14 encountered in the Dragon and Tandy Colour Computer.
15
17 -B, --bin
18 output raw binary file (default)
19 -D, --dragondos
21 output DragonDOS binary file
22 -C, --coco
24 output CoCo RS-DOS (“DECB”) segmented binary file
25 -S, --srec
27 output Motorola SREC file
28 -H, --hex
30 output Intel hex record file
31 -e, --exec addr
33 EXEC address (for output formats that support one)
34 -8, -9, --6809
36 use 6809 ISA (default)
37 -3, --6309
39 use 6309 ISA (6809 with extensions)
40 -d, --define sym[=number]
42 define a symbol
43 --setdp value
45 initial value assumed for DP [undefined]
46 -P, --max-passes n
48 maximum number of passes to allow symbol values to stabilise
49 [12]
50 -o, --output file
52 output filename
53 -l, --listing file
55 create listing file
56 -E, --exports file
58 create exports table
59 -s, --symbols file
61 create symbol table
62 -q, --quiet
64 don't warn about illegal (but working) code
65 -v, --verbose
67 warn about explicitly inefficient code
68 --help show help
70 --version
72 show program version
73 If more than one SOURCE-FILE is specified, they are assembled as though
75 they were all in one file.
76
78 Text is read in and parsed, then as many passes are made over the
79 parsed source as necessary (up to a limit), until symbols are resolved
80 and addresses are stable. The fastest or smallest representation should
81 always be chosen where there is ambiguity.
82 Output formats are: Raw binary, DragonDOS binary, CoCo RS-DOS (“DECB”)
84 binary, Motorola SREC, Intel HEX.
85 Additional optional output files are:
87 • A listing file is an annotated copy of the source file with addresses
89 and generated code prepended to each line.
90 • An exports file contains a list of all macro definitions and symbols
92 flagged for export with the EXPORT pseudo-op. Suitable for inclusion
93 in subsequent source files.
94 • A symbols file contains a list of all non-local symbols. Suitable for
96 inclusion in subsequent source files, but beware multiple definitions
97 errors if two source files include a common set of symbols.
98 Home page: <https://www.6809.org.uk/asm6809/>
100 Differences to other assemblers
102 Motorola syntax allows a comment to follow any operands, separated from
103 them only by whitespace. To an extent, this assembler accepts that, but
104 be aware that as spaces are allowed within expressions, if the comment
105 looks like it is continuing an expression it will generate bad code (or
106 raise an error if the result is syntactically incorrect). Example:
107 0000 8605 lda #5
109 0002 C60A ldb #5 * 2 twice first number
110 A strict Motorola assembler would generate bytes C6 05 for the second
112 line, as the “* 2” would be ignored. For consistency, it is best to in‐
113 troduce end of line comments with a ; character. An asterisk (*) can
114 introduce whole line comments.
115 An unquoted semicolon always introduces a comment. The alternate form
117 of the 6309 instructions AIM, OIM, etc. listed in some documentation
118 that uses a semicolon as a separator is not accepted.
119 A symbol may be forward referenced; any time a reference is unresolv‐
121 able, another pass is triggered, up to some defined maximum.
122 In 6809 indexed addressing, the offset size will default to the fastest
124 possible form, e.g. if the offset is an expression that happens to
125 evaluate to zero, the no offset form will be used. Prepend << to coerce
126 a 5 bit offset, < to coerce 8 bits or > to coerce 16 bits.
127 asm6809 currently has no support for OS-9 modules or multiple object
129 linking.
130 Program syntax
132 Program files are considered line by line. Each line contains up to
133 three fields, separated by whitespace: label, instruction and argu‐
134 ments. An unquoted semicolon (;) indicates that the rest of the line is
135 to be considered a comment. Whole line comments may be introduced with
136 an asterisk (*). Motorola-style end of line comments without a ; are
137 accepted, but see the notes about assembler differences.
138 Any label must appear at the very beginning of the line. If a label is
140 omitted, whitespace must appear before the operator field. Certain
141 pseudo-ops may affect a label's meaning, but usually labels define a
142 symbol referring to the current position in the code (Program Counter,
143 or PC).
144 The instruction field contains either an instruction op-code (mne‐
146 monic), a pseudo-op (assembler directive), or a macro name for expan‐
147 sion.
148 Pseudo-ops allow conditional assembly and inline data, can affect code
150 placement and symbol values and be used to include further files in‐
151 line. See the section on Pseudo-ops for more information.
152 Arguments are a comma-separated list: either instruction operands or
154 arguments to a pseudo-op or macro. Permitted arguments are specific to
155 the instruction or pseudo-op, but in general they may be:
156 • An expression.
158 • A register name, with optional pre-decrement or post-increment.
160 • A nested list surrounded by [ and ]. This is generally only used to
162 indicate indirect indexed addressing.
163 In addition, any argument may be preceded by:
165 • #, indicate immediate value.
167 • <<, force 5-bit index offset.
169 • <, force direct addressing, 8-bit value or 8-bit index offset.
171 • >, force extended addressing, 16-bit value or 16-bit index offset.
173 Expressions
175 Expressions are formed of:
176 • A decimal number.
178 • An octal number preceded by @ or with a leading 0.
180 • A binary number preceded by % or 0b.
182 • A hexadecimal number preceded by $ or 0x.
184 • A floating point number: decimal digits surrounding exactly one full
186 stop (.).
187 • A single quote followed by any ASCII character (yielding the ASCII
189 value of that character).
190 • A symbol name, local forward reference or local back reference.
192 • Any of the above prefixed with a unary minus (-) or plus (+).
194 • A string delimited either by double quotes or /.
196 • A combination of any of the above with arithmetic, bitwise, logical
198 or relational operators.
199 • Parenthesis to specify precedence.
201 The assembler uses multiple passes to resolve expressions. If an ex‐
203 pression refers to a symbol that cannot currently be resolved, an extra
204 pass is triggered. Similarly, if a symbol is assigned a value (e.g. by
205 an EQU pseudo-op) that differs to its value on the previous pass, an‐
206 other is triggered until it becomes stable.
207 When not directly used for their contents (e.g. by FCC), strings can be
209 used in place of integer values. The ASCII value of each character is
210 used to represent 8 bits of the integer result up to 32 bits. Example:
211 0000 CC443A ldd #"D:"
213 Operators
215 The following operators are available, listed in descending order of
216 precedence (where operators share a precedence, left-to-right evalua‐
217 tion is performed):
218 │
219 Operator │ Description
220 ───────────├──────────────────────
221 + │ unary plus
222 - │ unary minus
223 ! ~ │ logical, bitwise NOT
224 ───────────├──────────────────────
225 * │ multiplication
226 / │ division
227 % │ modulo
228 ───────────├──────────────────────
229 + │ addition
230 - │ subtraction
231 ───────────├──────────────────────
232 << │ bitwise shift left
233 >> │ bitwise shift right
234 ───────────├──────────────────────
235 < <= │ relational operators
236 > >= │ relational operators
237 ───────────├──────────────────────
238 == │ relational equal
239 != │ relational not equal
240 ───────────├──────────────────────
241 & │ bitwise AND
242 ───────────├──────────────────────
243 ^ │ bitwise XOR
244 ───────────├──────────────────────
245 | │ bitwise OR
246 ───────────├──────────────────────
247 && │ logical AND
248 ───────────├──────────────────────
249 || │ logical OR
250 ───────────├──────────────────────
251 ?: │ ternary operator
252 Division always returns a floating point result. Other arithmetic oper‐
254 ators return integers if both operands are integers, otherwise floating
255 point. Bitwise operators and modulo all cast their operands to integers
256 and return an integer. Relational and logical operators result in 0 if
257 false, 1 if true. Integer calculations are performed using the plat‐
258 form's int64_t type, floating point uses double.
259 Conditional assembly
261 The pseudo-ops IF, ELSIF, ELSE and ENDIF guide conditional assembly. IF
262 and ELSIF take one argument, which is evaluated as an integer. If the
263 result is non-zero, the following code will be assembled, else it will
264 be skipped. Undefined symbols encountered while evaluating the condi‐
265 tion are interpreted as zero (false) rather than raising an error.
266 Conditional assembly pseudo-ops are permitted within macro definitions
268 and will be evaluated at the time of expansion, therefore positional
269 variables can be used to affect macro expansion.
270 Sections
272 Code can be placed into named sections with the SECTION pseudo-op. This
273 can make breaking source into multiple input files more comfortable.
274 Without ORG or PUT directives, sections will follow each other in mem‐
275 ory in the order they are first defined.
276 Within each section, there may exist multiple spans of discontiguous
278 data. Certain output formats are able to represent this, for the others
279 (e.g. DragonDOS), the spans are combined first, with the gaps between
280 them padded with zero bytes.
281 Local labels
283 Local labels are considered local to the current section. A local label
284 is any decimal number used in the label field, and the same local label
285 may appear mulitple times, unlike other labels.
286 As an operand, a decimal number followed by B or F is considered to be
288 a back or forward reference to the previous or next occurrence of that
289 numerical local label in the section.
290 In this example, the 1 label occurs twice, but each use of 1B refers to
292 the closest one searching backwards:
293 0000 8E0400 scroll ldx #$0400
295 0003 EC8820 1 ldd 32,x
296 0006 ED81 std ,x++
297 0008 8C05E0 cmpx #$05e0
298 000B 25F6 blo 1B
299 000D CC6060 ldd #$6060
300 0010 ED81 1 std ,x++
301 0012 8C0600 cmpx #$0600
302 0015 25F9 blo 1B
303 0017 39 rts
304 An exclamation mark (!) in the label field is treated as a local label
306 numbered zero. Operands of < and > are considered equivalent to 0B and
307 0F respectively, and can therefore refer to the ! local label. This is
308 included for compatibility with other assemblers.
309 As local labels can be repeated, their position is used to distinguish
311 them. For this reason, all file inclusions and macro expansion must oc‐
312 cur during the first pass so that the absolute line count at which each
313 local label is encountered remains the same between passes.
314 Macros
316 Start a macro definition by specifying a name for it in the label
317 field, and MACRO in the instruction field. Finish the definition with
318 ENDM in the instruction field.
319 Use a macro by specifying its name in the instruction field. Any argu‐
321 ments given will be available during expansion as a positional vari‐
322 able.
323 Positional variables can be used within strings, or pasted to form sym‐
325 bol names. In either case, they must be quoted or they will be passed
326 by value, which will result in an error if they do not correspond to
327 valid symbols by themselves.
328 The positional variables are referred to with \{1}, \{2}, …, \{n}. For
330 the first nine arguments, the braces are not required, so \1, \2, …, \9
331 are valid alternatives. For compatibility with the TSC Flex assembler,
332 another form is accepted: &{1}, &{2}, …, &{n}. Within a string, the
333 shorter &1, &2, …, &9 is still valid, but as this can be confused with
334 bitwise AND, it is not permitted elsewhere.
335 Here's a silly example demonstrating positional variables and symbol
337 pasting. Consider the following macro definition and utilising code:
338 go_left equ -1
340 go_right equ +1
341 move macro
342 lda x_position
343 adda #go_\1
344 sta x_position
345 endm
346 do_move
347 move "right"
348 rts
349 x_position rmb 1
350 The main code generated is as follows:
352 0000 do_move
354 0000 move "right"
355 0000 B60009 lda x_position
356 0003 8B01 adda #go_\1
357 0005 B70009 sta x_position
358 0008 39 rts
359 Pseudo-ops
361 Conditional assembly:
362 IF condition
364 Subsequent lines are assembled only if condition evaluates to
365 true (non-zero).
366 ELSIF condition
368 Subsequent lines are assembled only if all preceding IF and EL‐
369 SIF pseudo-ops evaluated to false (zero) and condition evaluates
370 to true (non-zero).
371 ELSE Subsequent lines are assembled only if all preceding IF and EL‐
373 SIF pseudo-ops evaluated to false (zero).
374 ENDIF Terminate an IF statement.
376 Macro definition:
378 MACRO Start defining a macro. The macro's name shall be in the label
380 field. Subsequent lines up to the enclosing ENDM pseudo-op will
381 not be assembled until the macro is expanded. Macro definitions
382 may be nested; that is, using a macro may define another macro.
383 ENDM Finish a macro definition started with MACRO.
385 Inline data:
387 FCB value[,value]…
389 FCC value[,value]…
390 Form Constant Byte. Each value is evaluated either to a number
391 or a string. Numbers are truncated to 8 bits and stored directly
392 as bytes. For strings, the ASCII value of each character is
393 stored in sequential bytes.
394 Historically, FCB handled bytes and FCC (Form Constant Character
396 string) handled strings. asm6809 treats them as synonymous, but
397 is rather more strict about what is allowed as a string delim‐
398 iter.
399 FCN value[,value]…
401 Identical to FCC, but a terminating zero byte is stored after
402 the data. Included to increase compatibility with other assem‐
403 blers.
404 FCS value[,value]…
406 Like FCC, but the last byte in each value has its top bit set. This is
408 the format used to represent keywords in the Dragon and Tandy Colour
409 Computer BASIC ROMs.
410 FCV value[,value]…
412 Like FCC, but ASCII is translated into the values typically required
414 for display by the MC6847 VDG as present in the Dragon and Tandy Colour
415 Computer.
416 FCI value[,value]…
418 Like FCV, but inverts bit 6 for inverse video.
420 FDB value[,value]…
422 Form Double Byte. Each value is evaluated to a number, which is
423 truncated to 16 bits and stored as two successive bytes (big-en‐
424 dian).
425 FQB value[,value]…
427 Form Quad Byte. Each value is evaluated to a number, which is
428 truncated to 32 bits and stored as four successive bytes (big-
429 endian).
430 FILL value,count
432 Insert count bytes of value. This is effectively the same as the
433 two-argument form of RZB with its arguments swapped.
434 RZB count[,value]
436 ZMB count[,value]
437 BSZ count[,value]
438 Reserve Zeroed Bytes. Inserts a sequence of count bytes of zero,
439 or value if specified. The two-argument form is effectively the
440 same as FILL with its arguments swapped.
441 ZMB and BSZ are alternate forms recognised for compatibility
443 with other assemblers.
444 Code placement & addressing:
446 ALIGN alignment[,value]…
448 Align to memory next alignment bytes. Pads with value. If value
449 is not specified, this behaves like RMB instead.
450 ORG address
452 Sets the Program Counter—the base address assumed for the next
453 assembled instruction. Unless followed by a PUT pseudo-op, this
454 will also be the instruction's actual address in memory. A label
455 on the same line will define a symbol with a value of the speci‐
456 fied address.
457 PUT address
459 Modify the put address—the Program Counter is unaffected, so the
460 assumed address for subsequent instructions remains the same,
461 but the actual data will be located elsewhere. Useful for assem‐
462 bling code that is going to be copied into place before execut‐
463 ing.
464 RMB count
466 Reserve Memory Bytes. The Program Counter is advanced count
467 bytes. In some output formats this region may be padded with ze‐
468 roes, in others a new loadable section may be created.
469 SECTION name
471 CODE
472 DATA
473 BSS
474 RAM
475 AUTO Switch to the named section. The Program Counter will continue
476 from the last value it had while assembling this section, or
477 follow the previous section if had not previously been seen.
478 Each of CODE, DATA, BSS, RAM, and AUTO switches to a section
480 named after the pseudo-op. They are recognised for compatibility
481 with other assemblers.
482 SETDP page
484 Set the assumed value of the Direct Page (DP) register to page
485 for subsequent instructions. Any non-negative page is truncated
486 to 8 bits, or specify a negative number to disable automatic di‐
487 rect addressing.
488 See the section on Direct Page addressing for more information.
490 Symbols:
492 EQU value
494 Short for “equate”, this must be used with a label and defines a
495 symbol with the specified value. This may be any single valid
496 argument (e.g. an expression or a string).
497 EXPORT name[,name]…
499 Each name—either the name of a macro or a symbol—is flagged to
500 be exported. Exported macros and symbols will be listed in the
501 exports output file, if specified.
502 SET value
504 Similar to EQU, this must be used with a label and defines a
505 symbol with the specified value. Unlike EQU, you can use SET
506 multiple times to assign different values to the same symbol
507 without error.
508 Files:
510 END [address]
512 Signifies the end of input. All further lines are disregarded.
513 Optionally specifies an EXEC address to be included in the out‐
515 put, where supported by the output format. An EXEC address spec‐
516 ified on the command line will override any value specified
517 here.
518 INCLUDE filename
520 Includes the contents of another file at this point in assembly.
521 The filename argument must be a string, i.e. delimited by quotes
522 or / characters.
523 INCLUDEBIN filename
525 Includes the binary data from filename (which, as with INCLUDE
526 must be a delimited string) directly.
527 Direct Page addressing
529 The 6809 extends the zero page concept from other processors by allow‐
530 ing fast accesses to whichever page is selected by the Direct Page reg‐
531 ister (DP). An assembler is not able to keep track of what the code has
532 set this register to, but the information is useful when deciding which
533 addressing mode to use for an instruction. The SETDP pseudo-op, or
534 --setdp option, informs the assembler that the supplied value is to be
535 assumed for DP. Set this to a negative number to undefine it and dis‐
536 able automatic use of direct addressing (this is the default).
537
539 This program is free software: you can redistribute it and/or modify it
540 under the terms of the GNU General Public License as published by the
541 Free Software Foundation, either version 3 of the License, or (at your
542 option) any later version.
543 This program is distributed in the hope that it will be useful, but
545 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
546 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
547 Public License for more details.
548 You should have received a copy of the GNU General Public License along
550 with this program. If not, see <http://www.gnu.org/licenses/>.
551asm6809-2.13 June 2023 asm6809(1)