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