1asm6809(1)                  General Commands Manual                 asm6809(1)
2
3
4

NAME

6       asm6809—6809 cross-assembler
7

SYNOPSIS

9       asm6809 [OPTION]… [SOURCE-FILE]…
10

DESCRIPTION

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

OPTIONS

17       -B, --bin
18              output raw binary file (default)
19
20       -D, --dragondos
21              output DragonDOS binary file
22
23       -C, --coco
24              output CoCo RS-DOS (“DECB”) segmented binary file
25
26       -S, --srec
27              output Motorola SREC file
28
29       -H, --hex
30              output Intel hex record file
31
32       -e, --exec addr
33              EXEC address (for output formats that support one)
34
35       -8, -9, --6809
36              use 6809 ISA (default)
37
38       -3, --6309
39              use 6309 ISA (6809 with extensions)
40
41       -d, --define sym[=number]
42              define a symbol
43
44       --setdp value
45              initial value assumed for DP [undefined]
46
47       -P, --max-passes n
48              maximum  number  of  passes  to allow symbol values to stabilise
49              [12]
50
51       -o, --output file
52              output filename
53
54       -l, --listing file
55              create listing file
56
57       -E, --exports file
58              create exports table
59
60       -s, --symbols file
61              create symbol table
62
63       -q, --quiet
64              don't warn about illegal (but working) code
65
66       -v, --verbose
67              warn about explicitly inefficient code
68
69       --help show help
70
71       --version
72              show program version
73
74       If more than one SOURCE-FILE is specified, they are assembled as though
75       they were all in one file.
76

USAGE

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
83       Output formats are: Raw binary, DragonDOS binary, CoCo RS-DOS  (“DECB”)
84       binary, Motorola SREC, Intel HEX.
85
86       Additional optional output files are:
87
88       • A listing file is an annotated copy of the source file with addresses
89         and generated code prepended to each line.
90
91       • 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
95       • 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
99       Home page: <https://www.6809.org.uk/asm6809/>
100
101   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
108              0000  8605                  lda     #5
109              0002  C60A                  ldb     #5 * 2  twice first number
110
111       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
116       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
120       A  symbol  may be forward referenced; any time a reference is unresolv‐
121       able, another pass is triggered, up to some defined maximum.
122
123       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
128       asm6809  currently  has  no support for OS-9 modules or multiple object
129       linking.
130
131   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
139       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
145       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
149       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
153       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
157       • An expression.
158
159       • A register name, with optional pre-decrement or post-increment.
160
161       • A  nested  list surrounded by [ and ]. This is generally only used to
162         indicate indirect indexed addressing.
163
164       In addition, any argument may be preceded by:
165
166#, indicate immediate value.
167
168<<, force 5-bit index offset.
169
170<, force direct addressing, 8-bit value or 8-bit index offset.
171
172>, force extended addressing, 16-bit value or 16-bit index offset.
173
174   Expressions
175       Expressions are formed of:
176
177       • A decimal number.
178
179       • An octal number preceded by @ or with a leading 0.
180
181       • A binary number preceded by % or 0b.
182
183       • A hexadecimal number preceded by $ or 0x.
184
185       • A floating point number: decimal digits surrounding exactly one  full
186         stop (.).
187
188       • A  single  quote  followed by any ASCII character (yielding the ASCII
189         value of that character).
190
191       • A symbol name, local forward reference or local back reference.
192
193       • Any of the above prefixed with a unary minus (-) or plus (+).
194
195       • A string delimited either by double quotes or /.
196
197       • A combination of any of the above with arithmetic,  bitwise,  logical
198         or relational operators.
199
200       • Parenthesis to specify precedence.
201
202       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
208       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
212              0000  CC443A                ldd     #"D:"
213
214   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
253       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
260   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
267       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
271   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
277       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
282   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
287       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
291       In this example, the 1 label occurs twice, but each use of 1B refers to
292       the closest one searching backwards:
293
294              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
305       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
310       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
315   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
320       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
324       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
329       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
336       Here's  a  silly  example demonstrating positional variables and symbol
337       pasting. Consider the following macro definition and utilising code:
338
339              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
351       The main code generated is as follows:
352
353              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
360   Pseudo-ops
361       Conditional assembly:
362
363       IF condition
364              Subsequent lines are assembled only if  condition  evaluates  to
365              true (non-zero).
366
367       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
372       ELSE   Subsequent  lines are assembled only if all preceding IF and EL‐
373              SIF pseudo-ops evaluated to false (zero).
374
375       ENDIF  Terminate an IF statement.
376
377       Macro definition:
378
379       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
384       ENDM   Finish a macro definition started with MACRO.
385
386       Inline data:
387
388       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
395              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
400       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
405       FCS value[,value]…
406
407       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
411       FCV value[,value]…
412
413       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
417       FCI value[,value]…
418
419       Like FCV, but inverts bit 6 for inverse video.
420
421       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
426       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
431       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
435       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
442              ZMB and BSZ are alternate  forms  recognised  for  compatibility
443              with other assemblers.
444
445       Code placement & addressing:
446
447       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
451       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
458       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
465       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
470       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
479              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
483       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
489              See the section on Direct Page addressing for more information.
490
491       Symbols:
492
493       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
498       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
503       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
509       Files:
510
511       END [address]
512              Signifies the end of input. All further lines are disregarded.
513
514              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
519       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
524       INCLUDEBIN filename
525              Includes  the  binary data from filename (which, as with INCLUDE
526              must be a delimited string) directly.
527
528   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

LICENCE

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
544       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
549       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/>.
551
552
553
554asm6809-2.13                       June 2023                        asm6809(1)
Impressum