164tass v1.56 r2625 reference manual
2
3This is the manual for 64tass, the multi pass optimizing macro assembler for
4the 65xx series of processors. Key features:
5
6 * Open source portable C with minimal dependencies
7 * Familiar syntax to Omicron TASS and TASM
8 * Supports 6502, 65C02, R65C02, W65C02, 65CE02, 65816, DTV, 65EL02, 4510
9 * Arbitrary-precision integers and bit strings, double precision floating
10 point numbers
11 * Character and byte strings, array arithmetic
12 * Handles UTF-8, UTF-16 and 8 bit RAW encoded source files, Unicode character
13 strings
14 * Supports Unicode identifiers with compatibility normalization and optional
15 case insensitivity
16 * Built-in `linker' with section support
17 * Various memory models, binary targets and text output formats (also Hex/
18 S-record)
19 * Assembly and label listings available for debugging or exporting
20 * Conditional compilation, macros, structures, unions, scopes
21
22Contrary how the length of this document suggests 64tass can be used with just
23basic 6502 assembly knowledge in simple ways like any other assembler. If some
24advanced functionality is needed then this document can serve as a reference.
25
26This is a development version. Features or syntax may change as a result of
27corrections in non-backwards compatible ways in some rare cases. It's difficult
28to get everything `right' first time.
29
30Project page: https://sourceforge.net/projects/tass64/
31
32The page hosts the latest and older versions with sources and a bug and a
33feature request tracker.
34
35-------------------------------------------------------------------------------
36
37Table of Contents
38
39 * Table of Contents
40 * Usage tips
41 * Expressions and data types
42 + Integer constants
43 + Bit string constants
44 + Floating point constants
45 + Character string constants
46 + Byte string constants
47 + Lists and tuples
48 + Dictionaries
49 + Code
50 + Addressing modes
51 + Uninitialized memory
52 + Booleans
53 + Types
54 + Symbols
55 o Regular symbols
56 o Local symbols
57 o Anonymous symbols
58 o Constant and re-definable symbols
59 o The star label
60 + Built-in functions
61 o Mathematical functions
62 o Byte string functions
63 o Other functions
64 + Expressions
65 o Operators
66 o Comparison operators
67 o Bit string extraction operators
68 o Conditional operators
69 o Address length forcing
70 o Compound assignment
71 o Slicing and indexing
72 * Compiler directives
73 + Controlling the compile offset and program counter
74 + Dumping data
75 o Storing numeric values
76 o Storing string values
77 + Text encoding
78 + Structured data
79 o Structure
80 o Union
81 o Combined use of structures and unions
82 + Macros
83 o Parameter references
84 o Text references
85 + Custom functions
86 + Conditional assembly
87 o If, else if, else
88 o Switch, case, default
89 o Comment
90 + Repetitions
91 + Including files
92 + Scopes
93 + Sections
94 + 65816 related
95 + Controlling errors
96 + Target
97 + Misc
98 + Printer control
99 * Pseudo instructions
100 + Aliases
101 + Always taken branches
102 + Long branches
103 * Original turbo assembler compatibility
104 + How to convert source code for use with 64tass
105 + Differences to the original turbo ass macro on the C64
106 + Labels
107 + Expression evaluation
108 + Macros
109 + Bugs
110 * Command line options
111 + Output options
112 + Operation options
113 + Diagnostic options
114 + Target selection on command line
115 + Symbol listing
116 + Assembly listing
117 + Other options
118 + Command line from file
119 * Messages
120 + Warnings
121 + Errors
122 + Fatal errors
123 * Credits
124 * Default translation and escape sequences
125 + Raw 8-bit source
126 o The none encoding for raw 8-bit
127 o The screen encoding for raw 8-bit
128 + Unicode and ASCII source
129 o The none encoding for Unicode
130 o The screen encoding for Unicode
131 * Opcodes
132 + Standard 6502 opcodes
133 + 6502 illegal opcodes
134 + 65DTV02 opcodes
135 + Standard 65C02 opcodes
136 + R65C02 opcodes
137 + W65C02 opcodes
138 + W65816 opcodes
139 + 65EL02 opcodes
140 + 65CE02 opcodes
141 + CSG 4510 opcodes
142 * Appendix
143 + Assembler directives
144 + Built-in functions
145 + Built-in types
146
147-------------------------------------------------------------------------------
148
149Usage tips
150
15164tass is a command line assembler, the source can be written in any text
152editor. As a minimum the source filename must be given on the command line. The
153`-a' command line option is highly recommended if the source is Unicode or
154ASCII.
155
15664tass -a src.asm
157
158There are also some useful parameters which are described later.
159
160For comfortable compiling I use such `Makefile's (for make):
161
162demo.prg: source.asm macros.asm pic.drp music.bin
163 64tass -C -a -B -i source.asm -o demo.tmp
164 pucrunch -ffast -x 2048 demo.tmp >demo.prg
165
166This way `demo.prg' is recreated by compiling `source.asm' whenever
167`source.asm', `macros.asm', `pic.drp' or `music.bin' had changed.
168
169Of course it's not much harder to create something similar for win32
170(make.bat), however this will always compile and compress:
171
17264tass.exe -C -a -B -i source.asm -o demo.tmp
173pucrunch.exe -ffast -x 2048 demo.tmp >demo.prg
174
175Here's a slightly more advanced Makefile example with default action as testing
176in VICE, clean target for removal of temporary files and compressing using an
177intermediate temporary file:
178
179all: demo.prg
180 x64 -autostartprgmode 1 -autostart-warp +truedrive +cart $<
181
182demo.prg: demo.tmp
183 pucrunch -ffast -x 2048 $< >$@
184
185demo.tmp: source.asm macros.asm pic.drp music.bin
186 64tass -C -a -B -i $< -o $@
187
188.INTERMEDIATE: demo.tmp
189.PHONY: all clean
190clean:
191 $(RM) demo.prg demo.tmp
192
193It's useful to add a basic header to your source files like the one below, so
194that the resulting file is directly runnable without additional compression:
195
196* = $0801
197 .word (+), 2005 ;pointer, line number
198 .null $9e, format("%4d", start);will be sys 4096
199+ .word 0 ;basic line end
200
201* = $1000
202
203start rts
204
205A frequently coming up question is, how to automatically allocate memory,
206without hacks like *=*+1? Sure there's .byte and friends for variables with
207initial values but what about zero page, or RAM outside of program area? The
208solution is to not use an initial value by using `?' or not giving a fill byte
209value to .fill.
210
211* = $02
212p1 .addr ? ;a zero page pointer
213temp .fill 10 ;a 10 byte temporary area
214
215Space allocated this way is not saved in the output as there's no data to save
216at those addresses.
217
218What about some code running on zero page for speed? It needs to be relocated,
219and the length must be known to copy it there. Here's an example:
220
221 ldx #size(zpcode)-1;calculate length
222- lda zpcode,x
223 sta wrbyte,x
224 dex ;install to zero page
225 bpl -
226 jsr wrbyte
227 rts
228;code continues here but is compiled to run from $02
229zpcode .logical $02
230wrbyte sta $ffff ;quick byte writer at $02
231 inc wrbyte+1
232 bne +
233 inc wrbyte+2
234+ rts
235 .here
236
237The assembler supports lists and tuples, which does not seems interesting at
238first as it sound like something which is only useful when heavy scripting is
239involved. But as normal arithmetic operations also apply on all their elements
240at once, this could spare quite some typing and repetition.
241
242Let's take a simple example of a low/high byte jump table of return addresses,
243this usually involves some unnecessary copy/pasting to create a pair of tables
244with constructs like >(label-1).
245
246jumpcmd lda hibytes,x ; selected routine in X register
247 pha
248 lda lobytes,x ; push address to stack
249 pha
250 rts ; jump, rts will increase pc by one!
251; Build a list of jump addresses minus 1
252_ := (cmd_p, cmd_c, cmd_m, cmd_s, cmd_r, cmd_l, cmd_e)-1
253lobytes .byte <_ ; low bytes of jump addresses
254hibytes .byte >_ ; high bytes
255
256There are some other tips below in the descriptions.
257
258-------------------------------------------------------------------------------
259
260Expressions and data types
261
262Integer constants
263
264Integer constants can be entered as decimal digits of arbitrary length. An
265underscore can be used between digits as a separator for better readability of
266long numbers. The following operations are accepted:
267
268 Integer operators and functions
269x + y add x to y 2 + 2 is 4
270x - y subtract y from x 4 - 1 is 3
271x * y multiply x with y 2 * 3 is 6
272x / y integer divide x by y 7 / 2 is 3
273x % y integer modulo of x divided by y 5 % 2 is 1
274x ** y x raised to power of y 2 ** 4 is 16
275-x negated value -2 is -2
276+x unchanged +2 is 2
277~x -x - 1 ~3 is -4
278x | y bitwise or 2 | 6 is 6
279x ^ y bitwise xor 2 ^ 6 is 4
280x & y bitwise and 2 & 6 is 2
281x << y logical shift left 1 << 3 is 8
282x >> y arithmetic shift right -8 >> 3 is -1
283
284Integers are automatically promoted to float as necessary in expressions. Other
285types can be converted to integer using the integer type int.
286
287 .byte 23 ; as unsigned
288 .char -23 ; as signed
289
290; using negative integers as immediate values
291 ldx #-3 ; works as '#-' is signed immediate
292num = -3
293 ldx #+num ; needs explicit '#+' for signed 8 bits
294
295 lda #((bitmap >> 10) & $0f) | ((screen >> 6) & $f0)
296 sta $d018
297
298Bit string constants
299
300Bit string constants can be entered in hexadecimal form with a leading dollar
301sign or in binary with a leading percent sign. An underscore can be used
302between digits as a separator for better readability of long numbers. The
303following operations are accepted:
304
305 Bit string operators and functions
306~x invert bits ~%101 is ~%101
307y .. x concatenate bits $a .. $b is $ab
308y x n repeat %101 x 3 is %101101101
309x[n] extract bit(s) $a[1] is %1
310x[s] slice bits $1234[4:8] is $3
311x | y bitwise or ~$2 | $6 is ~$0
312x ^ y bitwise xor ~$2 ^ $6 is ~$4
313x & y bitwise and ~$2 & $6 is $4
314x << y bitwise shift left $0f << 4 is $0f0
315x >> y bitwise shift right ~$f4 >> 4 is ~$f
316
317Length of bit string constants are defined in bits and is calculated from the
318number of bit digits used including leading zeros.
319
320Bit strings are automatically promoted to integer or floating point as
321necessary in expressions. The higher bits are extended with zeros or ones as
322needed.
323
324Bit strings support indexing and slicing. This is explained in detail in
325section `Slicing and indexing'.
326
327Other types can be converted to bit string using the bit string type bits.
328
329 .byte $33 ; 8 bits in hexadecimal
330 .byte %00011111 ; 8 bits in binary
331 .text $1234 ; $34, $12 (little endian)
332
333 lda $01
334 and #~$07 ; 8 bits even after inversion
335 ora #$05
336 sta $01
337
338 lda $d015
339 and #~%00100000 ;clear a bit
340 sta $d015
341
342Floating point constants
343
344Floating point constants have a radix point in them and optionally an exponent.
345A decimal exponent is `e' while a binary one is `p'. An underscore can be used
346between digits as a separator for better readability. The following operations
347can be used:
348
349 Floating point operators and functions
350x + y add x to y 2.2 + 2.2 is 4.4
351x - y subtract y from x 4.1 - 1.1 is 3.0
352x * y multiply x with y 1.5 * 3 is 4.5
353x / y integer divide x by y 7.0 / 2.0 is 3.5
354x % y integer modulo of x divided by y 5.0 % 2.0 is 1.0
355x ** y x raised to power of y 2.0 ** -1 is 0.5
356-x negated value -2.0 is -2.0
357+x unchanged +2.0 is 2.0
358~x almost -x ~2.1 is almost -2.1
359x | y bitwise or 2.5 | 6.5 is 6.5
360x ^ y bitwise xor 2.5 ^ 6.5 is 4.0
361x & y bitwise and 2.5 & 6.5 is 2.5
362x << y logical shift left 1.0 << 3.0 is 8.0
363x >> y arithmetic shift right -8.0 >> 4 is -0.5
364
365As usual comparing floating point numbers for (non) equality is a bad idea due
366to rounding errors.
367
368The only predefined constant is pi.
369
370Floating point numbers are automatically truncated to integer as necessary.
371Other types can be converted to floating point by using the type float.
372
373Fixed point conversion can be done by using the shift operators. For example an
3748.16 fixed point number can be calculated as (3.14 << 16) & $ffffff. The binary
375operators operate like if the floating point number would be a fixed point one.
376This is the reason for the strange definition of inversion.
377
378 .byte 3.66e1 ; 36.6, truncated to 36
379 .byte $1.8p4 ; 4:4 fixed point number (1.5)
380 .sint 12.2p8 ; 8:8 fixed point number (12.2)
381
382Character string constants
383
384Character strings are enclosed in single or double quotes and can hold any
385Unicode character.
386
387Operations like indexing or slicing are always done on the original
388representation. The current encoding is only applied when it's used in
389expressions as numeric constants or in context of text data directives.
390
391Doubling the quotes inside string literals escapes them and results in a single
392quote.
393
394 Character string operators and functions
395y .. x concatenate strings "a" .. "b" is "ab"
396y in x is substring of "b" in "abc" is true
397a x n repeat "ab" x 3 is "ababab"
398a[i] character from start "abc"[1] is "b"
399a[-i] character from end "abc"[-1] is "c"
400a[:] no change "abc"[:] is "abc"
401a[s:] cut off start "abc"[1:] is "bc"
402a[:-s] cut off end "abc"[:-1] is "ab"
403a[s] reverse "abc"[::-1] is "cba"
404
405Character strings are converted to integers, byte and bit strings as necessary
406using the current encoding and escape rules. For example when using a sane
407encoding "z"-"a" is 25.
408
409Other types can be converted to character strings by using the type str or by
410using the repr and format functions.
411
412Character strings support indexing and slicing. This is explained in detail in
413section `Slicing and indexing'.
414
415mystr = "oeU" ; character string constant
416 .text 'it''s' ; it's
417 .word "ab"+1 ; conversion result is "bb" usually
418
419 .text "text"[:2] ; "te"
420 .text "text"[2:] ; "xt"
421 .text "text"[:-1] ; "tex"
422 .text "reverse"[::-1]; "esrever"
423
424Byte string constants
425
426Byte strings are like character strings, but hold bytes instead of characters.
427
428Quoted character strings prefixing by `b', `l', `n', `p', `s', `x' or `z'
429characters can be used to create byte strings. The resulting byte string
430contains what .text, .shiftl, .null, .ptext and .shift would create. Direct
431hexadecimal entry can be done using the `x' prefix and `z' denotes a z85
432encoded byte string. Spaces can be used between pairs of hexadecimal digits as
433a separator for better readability.
434
435 Byte string operators and functions
436y .. x concatenate strings x"12" .. x"34" is x"1234"
437y in x is substring of x"34" in x"1234" is true
438a x n repeat x"ab" x 3 is x"ababab"
439a[i] byte from start x"abcd12"[1] is x"cd"
440a[-i] byte from end x"abcd"[-1] is x"cd"
441a[:] no change x"abcd"[:] is x"abcd"
442a[s:] cut off start x"abcdef"[1:] is x"cdef"
443a[:-s] cut off end x"abcdef"[:-1] is x"abcd"
444a[s] reverse x"abcdef"[::-1] is x"efcdab"
445
446Byte strings support indexing and slicing. This is explained in detail in
447section `Slicing and indexing'.
448
449Other types can be converted to byte strings by using the type bytes.
450
451 .enc "screen" ;use screen encoding
452mystr = b"oeU" ;convert text to bytes, like .text
453 .enc "none" ;normal encoding
454
455 .text mystr ;text as originally encoded
456 .text s"p1" ;convert to bytes like .shift
457 .text l"p2" ;convert to bytes like .shiftl
458 .text n"p3" ;convert to bytes like .null
459 .text p"p4" ;convert to bytes like .ptext
460
461Binary data may be embedded in source code by using hexadecimal byte strings.
462This is more compact than using .byte followed by a lot of numbers. As expected
4631 byte becomes 2 characters.
464
465 .text x"fce2" ;2 bytes: $fc and $e2 (big endian)
466
467If readability is not a concern then the more compact z85 encoding may be used
468which encodes 4 bytes into 5 characters. Data lengths not a multiple of 4 are
469handled by omitting leading zeros in the last group.
470
471 .text z"FiUj*2M$hf";8 bytes: 80 40 20 10 08 04 02 01
472
473For data lengths of multiple of 4 bytes any z85 encoder will do. Otherwise the
474simplest way to encode a binary file into a z85 string is to create a source
475file which reads it using the line `label = binary('filename')'. Now if the
476labels are listed to a file then there will be a z85 encoded definition for
477this label.
478
479Lists and tuples
480
481Lists and tuples can hold a collection of values. Lists are defined from values
482separated by comma between square brackets [1, 2, 3], an empty list is [].
483Tuples are similar but are enclosed in parentheses instead. An empty tuple is
484(), a single element tuple is (4,) to differentiate from normal numeric
485expression parentheses. When nested they function similar to an array. Both
486types are immutable.
487
488 List and tuple operators and functions
489y .. x concatenate lists [1] .. [2] is [1, 2]
490y in x is member of list 2 in [1, 2, 3] is true
491a x n repeat [1, 2] x 2 is [1, 2, 1, 2]
492a[i] element from start ("1", 2)[1] is 2
493a[-i] element from end ("1", 2, 3)[-1] is 3
494a[:] no change (1, 2, 3)[:] is (1, 2, 3)
495a[s:] cut off start (1, 2, 3)[1:] is (2, 3)
496a[:-s] cut off end (1, 2.0, 3)[:-1] is (1, 2.0)
497a[s] reverse (1, 2, 3)[::-1] is (3, 2, 1)
498*a convert to arguments format("%d: %s", *mylist)
499... op a left fold ... + (1, 2, 3) is ((1+2)+3)
500a op ... right fold (1, 2, 3) - ... is (1-(2-3))
501
502Arithmetic operations are applied on the all elements recursively, therefore
503[1, 2] + 1 is [2, 3], and abs([1, -1]) is [1, 1].
504
505Arithmetic operations between lists are applied one by one on their elements,
506so [1, 2] + [3, 4] is [4, 6].
507
508When lists form an array and columns/rows are missing the smaller array is
509stretched to fill in the gaps if possible, so [[1], [2]] * [3, 4] is [[3, 4],
510[6, 8]].
511
512Lists and tuples support indexing and slicing. This is explained in detail in
513section `Slicing and indexing'.
514
515mylist = [1, 2, "whatever"]
516mytuple = (cmd_e, cmd_g)
517
518mylist = ("e", cmd_e, "g", cmd_g, "i", cmd_i)
519keys .text mylist[::2] ; keys ("e", "g", "i")
520call_l .byte <mylist[1::2]-1; routines (<cmd_e-1, <cmd_g-1, <cmd_i-1)
521call_h .byte >mylist[1::2]-1; routines (>cmd_e-1, >cmd_g-1, >cmd_i-1)
522
523Although lists elements of variables can't be changed using indexing (at the
524moment) the same effect can be achieved by combining slicing and concatenation:
525
526lst := lst[:2] .. [4] .. lst[3:]; same as lst[2] := 4 would be
527
528Folding is done on pair of elements either forward (left) or reverse (right).
529The list must contain at least one element. Here are some folding examples:
530
531minimum = size([part1, part2, part3]) <? ...
532maximum = size([part1, part2, part3]) >? ...
533sum = size([part1, part2, part3]) + ...
534xorall = list_of_numbers ^ ...
535join = list_of_strings .. ...
536allbits = sprites.(left, middle, right).bits | ...
537all = [true, true, true, true] && ...
538any = [false, false, false, true] || ...
539
540The range(start, end, step) built-in function can be used to create lists of
541integers in a range with a given step value. At least the end must be given,
542the start defaults to 0 and the step to 1. Sounds not very useful, so here are
543a few examples:
544
545;Bitmask table, 8 bits from left to right
546 .byte %10000000 >> range(8)
547;Classic 256 byte single period sinus table with values of 0-255.
548 .byte 128 + 127.5 * sin(range(256) * pi / 128)
549;Screen row address tables
550_ := $400 + range(0, 1000, 40)
551scrlo .byte <_
552scrhi .byte >_
553
554Dictionaries
555
556Dictionaries hold key and value pairs. Definition is done by collecting
557key:value pairs separated by comma between braces {"key":"value", :"default
558value"}.
559
560Looking up a non-existing key is normally an error unless a default value is
561given. An empty dictionary is {}. This type is immutable. There are limitations
562what may be used as a key but the value can be anything.
563
564 Dictionary operators and functions
565y .. x combine dictionaries {1:2, 3:4} .. {2:3, 3:1} is {1:2, 2:3, 3:1}
566x[i] value lookup {"1":2}["1"] is 2
567x.i symbol lookup {.ONE:1, .TWO:2}.ONE is 1
568y in x is a key 1 in {1:2} is true
569
570; Simple lookup
571 .text {1:"one", 2:"two"}[2]; "two"
572; 16 element "fader" table 1->15->12->11->0
573 .byte {1:15, 15:12, 12:11, :0}[range(16)]
574; Symbol accessible values. May be useful as a function return value too.
575coords = {.x: 24, .y: 50}
576 ldx #coords.x
577 ldy #coords.y
578
579Code
580
581Code holds the result of compilation in binary and other enclosed objects. In
582an arithmetic operation it's used as the numeric address of the memory where it
583starts. The compiled content remains static even if later parts of the source
584overwrite the same memory area.
585
586Indexing and slicing of code to access the compiled content might be
587implemented differently in future releases. Use this feature at your own risk
588for now, you might need to update your code later.
589
590 Label operators and functions
591a.b member label.locallabel
592a[i] element from start label[1]
593a[-i] element from end label[-1]
594a[:] copy as tuple label[:]
595a[s:] cut off start, as tuple label[1:]
596a[:-s] cut off end, as tuple label[:-1]
597a[s] reverse, as tuple label[::-1]
598
599mydata .word 1, 4, 3
600mycode .block
601local lda #0
602 .bend
603
604 ldx #size(mydata) ;6 bytes (3*2)
605 ldx #len(mydata) ;3 elements
606 ldx #mycode[0] ;lda instruction, $a9
607 ldx #mydata[1] ;2nd element, 4
608 jmp mycode.local ;address of local label
609
610Addressing modes
611
612Addressing modes are used for determining addressing modes of instructions.
613
614For indexing there must be no white space between the comma and the register
615letter, otherwise the indexing operator is not recognized. On the other hand
616put a space between the comma and a single letter symbol in a list to avoid it
617being recognized as an operator.
618
619 Addressing mode operators
620# immediate
621#+ signed immediate
622#- signed immediate
623( ) indirect
624[ ] long indirect
625,b data bank indexed
626,d direct page indexed
627,k program bank indexed
628,r data stack pointer indexed
629,s stack pointer indexed
630,x x register indexed
631,y y register indexed
632,z z register indexed
633
634Parentheses are used for indirection and square brackets for long indirection.
635These operations are only available after instructions and functions to not
636interfere with their normal use in expressions.
637
638Several addressing mode operators can be combined together. Currently the
639complexity is limited to 4 operators. This is enough to describe all addressing
640modes of the supported CPUs.
641
642 Valid addressing mode operator combinations
643# immediate lda #$12
644#+ signed immediate lda #+127
645#- signed immediate lda #-128
646#addr,#addr move mvp #5,#6
647addr direct or relative lda $12 lda $1234 bne $1234
648bit,addr direct page bit rmb 5,$12
649bit,addr,addr direct page bit relative jump bbs 5,$12,$1234
650(addr) indirect lda ($12) jmp ($1234)
651(addr),y indirect y indexed lda ($12),y
652(addr),z indirect z indexed lda ($12),z
653(addr,x) x indexed indirect lda ($12,x) jmp ($1234,x)
654[addr] long indirect lda [$12] jmp [$1234]
655[addr],y long indirect y indexed lda [$12],y
656#addr,b data bank indexed lda #0,b
657#addr,b,x data bank x indexed lda #0,b,x
658#addr,b,y data bank y indexed lda #0,b,y
659#addr,d direct page indexed lda #0,d
660#addr,d,x direct page x indexed lda #0,d,x
661#addr,d,y direct page y indexed ldx #0,d,y
662(#addr,d) direct page indirect lda (#$12,d)
663(#addr,d,x) direct page x indexed indirect lda (#$12,d,x)
664(#addr,d),y direct page indirect y indexed lda (#$12,d),y
665(#addr,d),z direct page indirect z indexed lda (#$12,d),z
666[#addr,d] direct page long indirect lda [#$12,d]
667[#addr,d],y direct page long indirect y indexed lda [#$12,d],y
668#addr,k program bank indexed jsr #0,k
669(#addr,k,x) program bank x indexed indirect jmp (#$1234,k,x)
670#addr,r data stack indexed lda #1,r
671(#addr,r),y data stack indexed indirect y indexed lda (#$12,r),y
672#addr,s stack indexed lda #1,s
673(#addr,s),y stack indexed indirect y indexed lda (#$12,s),y
674addr,x x indexed lda $12,x
675addr,y y indexed lda $12,y
676
677Direct page, data bank, program bank indexed and long addressing modes of
678instructions are intelligently chosen based on the instruction type, the
679address ranges set up by .dpage, .databank and the current program counter
680address. Therefore the `,d', `,b' and `,k' indexing is only used in very
681special cases.
682
683The immediate direct page indexed `#0,d' addressing mode is usable for direct
684page access. The 8 bit constant is a direct offset from the start of actual
685direct page. Alternatively it may be written as `0,d'.
686
687The immediate data bank indexed `#0,b' addressing mode is usable for data bank
688access. The 16 bit constant is a direct offset from the start of actual data
689bank. Alternatively it may be written as `0,b'.
690
691The immediate program bank indexed `#0,k' addressing mode is usable for program
692bank jumps, branches and calls. The 16 bit constant is a direct offset from the
693start of actual program bank. Alternatively it may be written as `0,k'.
694
695The immediate stack indexed `#0,s' and data stack indexed `#0,r' accept 8 bit
696constants as an offset from the start of (data) stack. These are sometimes
697written without the immediate notation, but this makes it more clear what's
698going on. For the same reason the move instructions are written with an
699immediate addressing mode `#0,#0' as well.
700
701The immediate (#) addressing mode expects unsigned values of byte or word size.
702Therefore it only accepts constants of 1 byte or in range 0-255 or 2 bytes or
703in range 0-65535.
704
705The signed immediate (#+ and #-) addressing mode is to allow signed numbers to
706be used as immediate constants. It accepts a single byte or an integer in range
707-128-127, or two bytes or an integer of -32768-32767.
708
709The use of signed immediate (like #-3) is seamless, but it needs to be
710explicitly written out for variables or expressions (#+variable). In case the
711unsigned variant is needed but the expression starts with a negation then it
712needs to be put into parentheses (#(-variable)) or else it'll change the
713address mode to signed.
714
715Normally addressing mode operators are used in expressions right after
716instructions. They can also be used for defining stack variable symbols when
717using a 65816, or to force a specific addressing mode.
718
719param = #1,s ;define a stack variable
720const = #1 ;immediate constant
721 lda #0,b ;always "absolute" lda $0000
722 lda param ;results in lda #$01,s
723 lda param+1 ;results in lda #$02,s
724 lda (param),y ;results in lda (#$01,s),y
725 ldx const ;results in ldx #$01
726 lda #-2 ;negative constant, $fe
727
728Uninitialized memory
729
730There's a special value for uninitialized memory, it's represented by a
731question mark. Whenever it's used to generate data it creates a `hole' where
732the previous content of memory is visible.
733
734Uninitialized memory holes without previous content are not saved unless it's
735really necessary for the output format, in that case it's replaced with zeros.
736
737It's not just data generation statements (e.g. .byte) that can create
738uninitialized memory, but .fill, .align or address manipulation as well.
739
740* = $200 ;bytes as necessary
741 .word ? ;2 bytes
742 .fill 10 ;10 bytes
743 .align 64 ;bytes as necessary
744
745Booleans
746
747There are two predefined boolean constant variables, true and false.
748
749Booleans are created by comparison operators (<, <=, !=, ==, >=, >), logical
750operators (&&, ||, ^^, !), the membership operator (in) and the all and any
751functions.
752
753Normally in numeric expressions true is 1 and false is 0, unless the `
754-Wstrict-bool' command line option was used.
755
756Other types can be converted to boolean by using the type bool.
757
758 Boolean values of various types
759bits At least one non-zero bit
760bool When true
761bytes At least one non-zero byte
762code Address is non-zero
763float Not 0.0
764int Not zero
765str At least one non-zero byte after translation
766
767Types
768
769The various types mentioned earlier have predefined names. These can used for
770conversions or type checks.
771
772 Built-in type names
773address Address type
774bits Bit string type
775bool Boolean type
776bytes Byte string type
777code Code type
778dict Dictionary type
779float Floating point type
780gap Uninitialized memory type
781int Integer type
782list List type
783str Character string type
784tuple Tuple type
785type Type type
786
787Bit and byte string conversions can take a second parameter to specify and
788exact size. Values which can fit in shorter space will be padded but longer
789ones give an error.
790
791bits(<expression>, <bits count expression>)
792 Convert to the specific number of bits. If the number of bits is negative
793 then it's a signed.
794bytes(<expression>, <byte count expression>)
795 Convert to the specific number of bytes. If the number of bits is negative
796 then it's a signed.
797
798 .cerror type(var) != str, "Not a string!"
799 .text str(year) ; convert to string
800
801Symbols
802
803Symbols are used to reference objects. Regularly named, anonymous and local
804symbols are supported. These can be constant or re-definable.
805
806Scopes are where symbols are stored and looked up. The global scope is always
807defined and it can contain any number of nested scopes.
808
809Symbols must be uniquely named in a scope, therefore in big programs it's hard
810to come up with useful and easy to type names. That's why local and anonymous
811symbols exists. And grouping certain related symbols into a scope makes sense
812sometimes too.
813
814Scopes are usually created by .proc and .block directives, but there are a few
815other ways. Symbols in a scope can be accessed by using the dot operator, which
816is applied between the name of the scope and the symbol (e.g.
817myconsts.math.pi).
818
819Regular symbols
820
821Regular symbol names are starting with a letter and containing letters, numbers
822and underscores. Unicode letters are allowed if the `-a' command line option
823was used. There's no restriction on the length of symbol names.
824
825Care must be taken to not use duplicate names in the same scope when the symbol
826is used as a constant as there can be only one definition for them.
827
828Duplicate names in parent scopes are not a problem and this gives the ability
829to override names defined in lower scopes. However this can just as well lead
830to mistakes if a lower scoped symbol with the same name was meant so there's a
831-Wshadow command line option to warn if such ambiguity exists.
832
833Case sensitivity can be enabled with the `-C' command line option, otherwise
834all symbols are matched case insensitive.
835
836For case insensitive matching it's possible to check for consistent symbol name
837use with the `-Wcase-symbol' command line option.
838
839A regular symbol is looked up first in the current scope, then in lower scopes
840until the global scope is reached.
841
842f .block
843g .block
844n nop ;jump here
845 .bend
846 .bend
847
848 jsr f.g.n ;reference from a scope
849f.x = 3 ;create x in scope f with value 3
850
851Local symbols
852
853Local symbols have their own scope between two regularly named code symbols and
854are assigned to the code symbol above them.
855
856Therefore they're easy to reuse without explicit scope declaration directives.
857
858Not all regularly named symbols can be scope boundaries just plain code symbol
859ones without anything or an opcode after them (no macros!). Symbols defined as
860procedures, blocks, macros, functions, structures and unions are ignored. Also
861symbols defined by .var, := or = don't apply, and there are a few more
862exceptions, so stick to using plain code labels.
863
864The name must start with an underscore (_), otherwise the same character
865restrictions apply as for regular symbols. There's no restriction on the length
866of the name.
867
868Care must be taken to not use the duplicate names in the same scope when the
869symbol is used as a constant.
870
871A local symbol is only looked up in it's own scope and nowhere else.
872
873incr inc ac
874 bne _skip
875 inc ac+1
876_skip rts
877
878decr lda ac
879 bne _skip
880 dec ac+1
881_skip dec ac ;symbol reused here
882 jmp incr._skip ;this works too, but is not advised
883
884Anonymous symbols
885
886Anonymous symbols don't have a unique name and are always called as a single
887plus or minus sign. They are also called as forward (+) and backward (-)
888references.
889
890When referencing them `-' means the first backward, `--' means the second
891backwards and so on. It's the same for forward, but with `+'. In expressions it
892may be necessary to put them into brackets.
893
894 ldy #4
895- ldx #0
896- txa
897 cmp #3
898 bcc +
899 adc #44
900+ sta $400,x
901 inx
902 bne -
903 dey
904 bne --
905
906Excessive nesting or long distance references create poorly readable code. It's
907also very easy to copy-paste a few lines of code with these references into a
908code fragment already containing similar references. The result is usually a
909long debugging session to find out what went wrong.
910
911These references are also useful in segments, but this can create a nice trap
912when segments are copied into the code with their internal references.
913
914 bne +
915 #somemakro ;let's hope that this segment does
916+ nop ;not contain forward references...
917
918Anonymous symbols are looked up first in the current scope, then in lower
919scopes until the global scope is reached.
920
921Anonymous labels within conditionally assembled code are counted even if the
922code itself is not compiled and the label won't get defined. This ensures that
923anonymous labels are always at the same "distance" independent of the
924conditions in between.
925
926Constant and re-definable symbols
927
928Constant symbols can be created with the equal sign. These are not
929re-definable. Forward referencing of them is allowed as they retain the objects
930over compilation passes.
931
932Symbols in front of code or certain assembler directives are created as
933constant symbols too. They are bound to the object following them.
934
935Re-definable symbols can be created by the .var directive or := construct.
936These are also called as variables. They don't carry their content over from
937the previous pass therefore it's not possible to use them before their
938definition.
939
940Variables can be conditionally defined using the :?= construct. If the variable
941was defined already then the original value is retained otherwise a new one is
942created with this value.
943
944WIDTH = 40 ;a constant
945 lda #WIDTH ;lda #$28
946variabl .var 1 ;a variable
947var2 := 1 ;another variable
948variabl .var variabl + 1;update it verbosely
949var2 += 1 ;compound assignment (add one)
950var3 :?= 5 ;assign 5 if undefined
951
952The star label
953
954The `*' symbol denotes the current program counter value. When accessed it's
955value is the program counter at the beginning of the line. Assigning to it
956changes the program counter and the compiling offset.
957
958Built-in functions
959
960Built-in functions are pre-assigned to the symbols listed below. If you reuse
961these symbols in a scope for other purposes then they become inaccessible, or
962can perform a different function.
963
964Built-in functions can be assigned to symbols (e.g. sinus = sin), and the new
965name can be used as the original function. They can even be passed as
966parameters to functions.
967
968Mathematical functions
969
970floor(<expression>)
971 Round down. E.g. floor(-4.8) is -5.0
972round(<expression>)
973 Round to nearest away from zero. E.g. round(4.8) is 5.0
974ceil(<expression>)
975 Round up. E.g. ceil(1.1) is 2.0
976trunc(<expression>)
977 Round down towards zero. E.g. trunc(-1.9) is -1
978frac(<expression>)
979 Fractional part. E.g. frac(1.1) is 0.1
980sqrt(<expression>)
981 Square root. E.g. sqrt(16.0) is 4.0
982cbrt(<expression>)
983 Cube root. E.g. cbrt(27.0) is 3.0
984log10(<expression>)
985 Common logarithm. E.g. log10(100.0) is 2.0
986log(<expression>)
987 Natural logarithm. E.g. log(1) is 0.0
988exp(<expression>)
989 Exponential. E.g. exp(0) is 1.0
990pow(<expression a>, <expression b>)
991 A raised to power of B. E.g. pow(2.0, 3.0) is 8.0
992sin(<expression>)
993 Sine. E.g. sin(0.0) is 0.0
994asin(<expression>)
995 Arc sine. E.g. asin(0.0) is 0.0
996sinh(<expression>)
997 Hyperbolic sine. E.g. sinh(0.0) is 0.0
998cos(<expression>)
999 Cosine. E.g. cos(0.0) is 1.0
1000acos(<expression>)
1001 Arc cosine. E.g. acos(1.0) is 0.0
1002cosh(<expression>)
1003 Hyperbolic cosine. E.g. cosh(0.0) is 1.0
1004tan(<expression>)
1005 Tangent. E.g. tan(0.0) is 0.0
1006atan(<expression>)
1007 Arc tangent. E.g. atan(0.0) is 0.0
1008tanh(<expression>)
1009 Hyperbolic tangent. E.g. tanh(0.0) is 0.0
1010rad(<expression>)
1011 Degrees to radian. E.g. rad(0.0) is 0.0
1012deg(<expression>)
1013 Radian to degrees. E.g. deg(0.0) is 0.0
1014hypot(<expression y>, <expression x>)
1015 Polar distance. E.g. hypot(4.0, 3.0) is 5.0
1016atan2(<expression y>, <expression x>)
1017 Polar angle in -pi to +pi range. E.g. atan2(0.0, 3.0) is 0.0
1018abs(<expression>)
1019 Absolute value. E.g. abs(-1) is 1
1020sign(<expression>)
1021 Returns the sign of value as -1, 0 or 1 for negative, zero and positive.
1022 E.g. sign(-5) is -1
1023
1024Byte string functions
1025
1026These functions return byte strings of various lengths for signed numbers,
1027unsigned numbers and addresses.
1028
1029The naming of functions is not a coincidence and they return the bytes what the
1030data directives with the same names normally emit.
1031
1032byte(<expression>)
1033char(<expression>)
1034 Return a single byte string from a 8 bit unsigned (0-255) or signed number
1035 (-128-127). E.g. byte(0) is x"00" and char(-1) is x"ff"
1036word(<expression>)
1037sint(<expression>)
1038 Return a little endian byte string of 2 bytes from a 16 bit unsigned
1039 (0-65535) or signed number (-32768-32767). E.g. word(1024) is x"0004" and
1040 sint(-1) is x"ffff"
1041long(<expression>)
1042lint(<expression>)
1043 Return a little endian byte string of 3 bytes from a 24 bit unsigned
1044 (0-16777216) or signed number (-8388608-8388607). E.g. long(123456) is
1045 x"40E201" and lint(-1) is x"ffffff"
1046dword(<expression>)
1047dint(<expression>)
1048 Return a little endian byte string of 4 bytes from a 32 bit unsigned
1049 (0-4294967296) or signed number (-2147483648-2147483647). E.g. dword(
1050 123456789) is x"15CD5B07" and dint(-1) is x"ffffffff"
1051addr(<expression>)
1052 Return a little endian byte string of 2 bytes from an address in the
1053 current program bank. E.g. addr(start) is x"0d08"
1054rta(<expression>)
1055 Return a little endian byte string of 2 bytes from a return address in the
1056 current program bank. E.g. rta(4096) is x"ff0f"
1057
1058Other functions
1059
1060all(<expression>)
1061 Return truth for various definitions of `all'.
1062
1063 All function
1064 all bits set or no bits at all all($f) is true
1065 all characters non-zero or empty all("c") is true
1066 string
1067 all bytes non-zero or no bytes all(x"ac24") is true
1068 all elements true or empty list all([true, true, false]) is false
1069
1070 Only booleans in a list are accepted with the `-Wstrict-bool' command line
1071 option.
1072
1073any(<expression>)
1074 Return truth for various definitions of `any'.
1075
1076 Any function
1077 at least one bit set any(~$f) is false
1078 at least one non-zero character any("c") is true
1079 at least one non-zero byte any(x"ac24") is true
1080 at least one true element any([true, true, false]) is true
1081
1082 Only booleans in a list are accepted with the `-Wstrict-bool' command line
1083 option.
1084
1085binary(<string expression>[, <offset>[, <length>]])
1086 Returns the binary file content as bytes.
1087
1088 This function reads the content of a binary file as a byte string. It also
1089 accepts optional offset and length parameters.
1090
1091 Binary function invocation types
1092 Read everything binary(name)
1093 Skip starting bytes binary(name, offset)
1094 Some bytes from offset binary(name, offset, length)
1095
1096 sidfile = "music.sid" ; file name
1097 header = binary(sidfile, $00, $7e)
1098 init = header[$b:$9:-1] ; init address (big endian)
1099 play = header[$d:$b:-1] ; play address (big endian)
1100
1101 * = header[$7c:$7e] ; use loading address (little endian)
1102 .binary sidfile, $7e ; load music data
1103
1104format(<string expression>[, <expression>, ...])
1105 Create string from values according to a format string.
1106
1107 The format function converts a list of values into a character string. The
1108 converted values are inserted in place of the % sign. Optional conversion
1109 flags and minimum field length may follow, before the conversion type
1110 character. These flags can be used:
1111
1112 Formatting flags
1113 # alternate form ($a, %10, 10.)
1114 * width/precision from list
1115 . precision
1116 0 pad with zeros
1117 - left adjusted (default right)
1118 blank when positive or minus sign
1119 + sign even if positive
1120
1121 The following conversion types are implemented:
1122
1123 Formatting conversion types
1124 b binary
1125 c Unicode character
1126 d decimal
1127 e E exponential float (uppercase)
1128 f F floating point (uppercase)
1129 g G exponential/floating point
1130 s string
1131 r representation
1132 x X hexadecimal (uppercase)
1133 % percent sign
1134
1135 .text format("%#04x bytes left", 1000); $03e8 bytes left
1136
1137len(<expression>)
1138 Returns the number of elements.
1139
1140 Length of various types
1141 bit string length in bits len($034) is 12
1142 character string number of characters len("abc") is 3
1143 byte string number of bytes len(x"abcd23") is 3
1144 tuple, list number of elements len([1, 2, 3]) is 3
1145 dictionary number of elements len({1:2, 3:4]) is 2
1146 code number of elements len(label)
1147
1148random([<expression>, ...])
1149 Returns a pseudo random number.
1150
1151 The sequence does not change across compilations and is the same every
1152 time. Different sequences can be generated by seeding with .seed.
1153
1154 Random function invocation types
1155 floating point number 0.0 <= x < 1.0 random()
1156 integer in range of 0 <= x < e random(e)
1157 integer in range of s <= x < e random(s, a)
1158 integer in range of s <= x < e, step t random(s, a, t)
1159
1160 .seed 1234 ; default is boring, seed the generator
1161 .byte random(256); a pseudo random byte (0-255)
1162 .byte random([16] x 8); 8 pseudo random bytes (0-15)
1163
1164range(<expression>[, <expression>, ...])
1165 Returns a list of integers in a range, with optional stepping.
1166
1167 Range function invocation types
1168 integers from 0 to e-1 range(e)
1169 integers from s to e-1 range(s, a)
1170 integers from s to e (not including e), step t range(s, a, t)
1171
1172 .byte range(16) ; 0, 1, ..., 14, 15
1173 .char range(-5, 6); -5, -4, ..., 4, 5
1174 mylist = range(10, 0, -2); [10, 8, 6, 4, 2]
1175
1176repr(<expression>)
1177 Returns a string representation of value.
1178
1179 .warn repr(var) ; pretty print value, for debugging
1180
1181size(<expression>)
1182 Returns the size of code, structure or union in bytes.
1183
1184 var .word 0, 0, 0
1185 ldx #size(var) ; 6 bytes
1186 var2 = var + 2 ; start 2 bytes later
1187 ldx #size(var2) ; what remains is 4 bytes
1188
1189sort(<list expression>)
1190 Returns a sorted list or tuple.
1191
1192 If the original list contains further lists then these must be all of the
1193 same length. In this case the order of lists is determined by comparing
1194 their elements from the start until a difference is found. The sort is
1195 stable.
1196
1197 ; sort IRQ routines by their raster lines
1198 sorted = sort([(60, irq1), (50, irq2)])
1199 lines .byte sorted[:, 0] ; 50, 60
1200 irqs .addr sorted[:, 1] ; irq2, irq1
1201
1202Expressions
1203
1204Operators
1205
1206The following operators are available. Not all are defined for all types of
1207arguments and their meaning might slightly vary depending on the type.
1208
1209 Unary operators
1210- negative + positive
1211! not ~ invert
1212* convert to arguments ^ decimal string
1213
1214The `^' decimal string operator will be changed to mean the bank byte soon.
1215Please update your sources to use format("%d", xxx) instead! This is done to be
1216in line with it's use in most other assemblers.
1217
1218 Binary operators
1219+ add - subtract
1220* multiply / divide
1221% modulo ** raise to power
1222| binary or ^ binary xor
1223& binary and << shift left
1224>> shift right . member
1225.. concat x repeat
1226in contains
1227
1228Spacing must be used for the `x' and `in' operators or else they won't be
1229recognized as such. For example the expression `[1,2]x2' should be written as
1230`[1,2]x 2' instead.
1231
1232Parenthesis (( )) can be used to override operator precedence. Don't forget
1233that they also denote indirect addressing mode for certain opcodes.
1234
1235 lda #(4+2)*3
1236
1237Comparison operators
1238
1239Traditional comparison operators give false or true depending on the result.
1240
1241The compare operator (<=>) gives -1 for less, 0 for equal and 1 for more.
1242
1243 Comparison operators
1244<=> compare === identical
1245== equals != not equal
1246< less than >= more than or equals
1247> more than <= less than or equals
1248
1249Bit string extraction operators
1250
1251These unary operators extract 8 or 16 bits. Usually they are used to get parts
1252of a memory address.
1253
1254 Bit string extraction operators
1255< lower byte > higher byte
1256<> lower word >` higher word
1257>< lower byte swapped word ` bank byte
1258
1259 lda #<label ; low byte of address
1260 ldy #>label ; high byte of address
1261 jsr $ab1e
1262
1263 ldx #<>source ; word extraction
1264 ldy #<>dest
1265 lda #size(source)-1
1266 mvn #`source, #`dest; bank extraction
1267
1268Please note that these prefix operators are not strongly binding like negation
1269or inversion. Instead they apply to the whole expression to the right. This may
1270be unexpected but is required for compatibility with old sources which expect
1271this behaviour.
1272
1273 lda #<label+10 ;This is <(label+10) and not (<label)+10
1274
1275;The check below is wrong and should be written as (>start) != (>end)
1276 .cerror >start != >end;Effectively this is >(start != (>end))
1277
1278Conditional operators
1279
1280Boolean conditional operators give false or true or one of the operands as the
1281result.
1282
1283 Logical and conditional operators
1284x || y if x is true then x otherwise y
1285x ^^ y if both false or true then false otherwise x || y
1286x && y if x is true then y otherwise x
1287!x if x is true then false otherwise true
1288c ? x : y if c is true then x otherwise y
1289c ?? x : y if c is true then x otherwise y (broadcasting)
1290x <? y if x is smaller then x otherwise y
1291x >? y if x is greater then x otherwise y
1292
1293;Silly example for 1=>"simple", 2=>"advanced", else "normal"
1294 .text MODE == 1 && "simple" || MODE == 2 && "advanced" || "normal"
1295 .text MODE == 1 ? "simple" : MODE == 2 ? "advanced" : "normal"
1296;Limit result to 0 .. 8
1297light .byte 0 >? range(-16, 101)/6 <? 8
1298
1299Please note that these are not short circuiting operations and both sides are
1300calculated even if thrown away later.
1301
1302With the `-Wstrict-bool' command line option booleans are required as arguments
1303and only the `?' operator may return something else.
1304
1305Address length forcing
1306
1307Special addressing length forcing operators in front of an expression can be
1308used to make sure the expected addressing mode is used. Only applicable when
1309used directly at the mnemonic.
1310
1311 Address size forcing
1312@b to force 8 bit address
1313@w to force 16 bit address
1314@l to force 24 bit address (65816)
1315
1316 lda @w $0000 ; force the use of 2 byte absolute addressing
1317 bne @b label ; prevent upgrade to beq+jmp with long branches in use
1318 lda @w #$00 ; use 2 bytes independent of accumulator size
1319
1320Compound assignment
1321
1322These assignment operators are short hands for updating variables.
1323
1324The variables on the left must be defined beforehand by `:=' or `.var'.
1325Constants can't be changed of course.
1326
1327 Compound assignments
1328+= add -= subtract
1329*= multiply /= divide
1330%= modulo **= raise to power
1331|= binary or ^= binary xor
1332&= binary and ||= logical or
1333&&= logical and <<= shift left
1334>>= shift right ..= concat
1335<?= smaller >?= greater
1336x= repeat .= member
1337
1338v += 1 ; same as 'v .var v + 1'
1339
1340Slicing and indexing
1341
1342Lists, character strings, byte strings and bit strings support various slicing
1343and indexing possibilities through the [] operator.
1344
1345Indexing elements with positive integers is zero based. Negative indexes are
1346transformed to positive by adding the number of elements to them, therefore -1
1347is the last element. Indexing with list of integers is possible as well so [1,
13482, 3][(-1, 0, 1)] is [3, 1, 2].
1349
1350Slicing is an operation when parts of sequence is extracted from a start
1351position to an end position with a step value. These parameters are separated
1352with colons enclosed in square brackets and are all optional. Their default
1353values are [start:maximum:step=1]. Negative start and end characters are
1354converted to positive internally by adding the length of string to them.
1355Negative step operates in reverse direction, non-single steps will jump over
1356elements.
1357
1358This is quite powerful and therefore a few examples will be given here:
1359
1360Positive indexing a[x]
1361 It'll simply extracts a numbered element. It is zero based, therefore
1362 "abcd"[1] results in "b".
1363Negative indexing a[-x]
1364 This extracts an element counted from the end, -1 is the last one. So
1365 "abcd"[-2] results in "c".
1366Cut off end a[:to]
1367 Extracts a continuous range stopping before `to'. So [10,20,30,40][:-1]
1368 results in [10,20,30].
1369Cut off start a[from:]
1370 Extracts a continuous range starting from `from'. So [10,20,30,40][-2:]
1371 results in [30,40].
1372Slicing a[from:to]
1373 Extracts a continuous range starting from element `from' and stopping
1374 before `to'. The two end positions can be positive or negative indexes. So
1375 [10,20,30,40][1:-1] results in [20,30].
1376Everything a[:]
1377 Giving no start or end will cover everything and therefore results in a
1378 complete copy.
1379Reverse a[::-1]
1380 This gives everything in reverse, so "abcd"[::-1] is "dcba".
1381Stepping through a[from:to:step]
1382 Extracts every `step'th element starting from `from' and stopping before
1383 `to'. So "abcdef"[1:4:2] results in "bd". The `from' and `to' can be
1384 omitted in case it starts from the beginning or end at the end. If the
1385 `step' is negative then it's done in reverse.
1386Extract multiple elements a[list]
1387 Extract elements based on a list. So "abcd"[[1,3]] will be "bd".
1388
1389The fun start with nested lists and tuples, as these can be used to create a
1390matrix. The examples will be given for a two dimensional matrix for easier
1391understanding, but this also works in higher dimensions.
1392
1393Extract row a[x]
1394 Given a [(1,2),(3,4)] matrix [0] will give the first row which is (1,2)
1395Extract row range a[from:to]
1396 Given a [(1,2),(3,4),(5,6),(7,8)] matrix [1:3] will give [(3,4),(5,6)]
1397Extract column a[x]
1398 Given a [(1,2),(3,4)] matrix [:,0] will give the first column of all rows
1399 which is [1,3]
1400Extract column range a[:,from:to]
1401 Given a [(1,2,3,4),(5,6,7,8)] matrix [:,1:3] will give [(2,3),(6,7)]
1402
1403And it works for list of indexes, negative indexes, stepped ranges, reversing,
1404etc. on all axes in too many ways to show all possibilities.
1405
1406Basically it's just the indexing and slicing applied on nested constructs,
1407where each nesting level is separated by a comma.
1408
1409-------------------------------------------------------------------------------
1410
1411Compiler directives
1412
1413Controlling the compile offset and program counter
1414
1415Two counters are used while assembling.
1416
1417The compile offset is where the data and code ends up in memory (or in image
1418file).
1419
1420The program counter is what labels get set to and what the special star label
1421refers to.
1422
1423Normally both are the same (code is compiled to the location it runs from) but
1424it does not need to be.
1425
1426*= <expression>
1427 The compile offset is adjusted so that the program counter will match the
1428 requested address in the expression.
1429
1430 ;Offset ;PC ;Hex ;Monitor ;Source
1431 * = $0800
1432 .0800 label1
1433 .logical $1000
1434 .0800 1000 label2
1435 * = $1200
1436 .0a00 1200 label3
1437 .here
1438 .0a00 label4
1439
1440.offs <expression>
1441 Sets the compile offset relative to the program counter.
1442
1443 Popular in old TASM code where this was the only way to create relocated
1444 code, otherwise it's use is not recommended as there are easier to use
1445 alternatives below.
1446
1447 ;Offset ;PC ;Hex ;Monitor ;Source
1448 * = $1000
1449 .1000 ea nop nop
1450 .offs 100
1451 .1065 1001 ea nop nop
1452
1453.logical <expression>
1454 Starts a relocation block
1455.here
1456.endlogical
1457 Ends a relocation block
1458
1459 Changes the program counter only, the compile offset is not changed. When
1460 finished all continues where it was left off before.
1461
1462 The naming is not logical at all for relocated code, but that's how it was
1463 named in old 6502tass.
1464
1465 It's used for code copied to it's proper location at runtime. Can be nested
1466 of course.
1467
1468 ;Offset ;PC ;Hex ;Monitor ;Source
1469 * = $1000
1470 .logical $300
1471 .1000 0300 a9 80 lda #$80 drive lda #$80
1472 .1002 0302 85 00 sta $00 sta $00
1473 .1004 0304 4c 00 03 jmp $0300 jmp drive
1474 .here
1475
1476.virtual [<expression>]
1477 Starts a virtual block
1478.endv
1479.endvirtual
1480 Ends a virtual block
1481
1482 Changes the program counter to the expression (if given) and discards the
1483 result of compilation. This is useful to define structures to fixed
1484 addresses.
1485
1486 .virtual $d400 ; base address
1487 sid .block
1488 freq .word ? ; frequency
1489 pulsew .word ? ; pulse width
1490 control .byte ? ; control
1491 ad .byte ? ; attack/decay
1492 sr .byte ? ; sustain/release
1493 .bend
1494 .endvirtual
1495
1496 Or to define stack "allocated" variables on 65816.
1497
1498 .virtual #1,s
1499 p1 .addr ? ; at #1,s
1500 tmp .byte ? ; at #3,s
1501 .endvirtual
1502 lda (p1),y ; lda ($01,s),y
1503
1504.align <expression>[, <fill>]
1505 Align the program counter to a dividable address by inserting uninitialized
1506 memory or repeated bytes.
1507
1508 Usually used to page align data or code to avoid penalty cycles when
1509 indexing or branching.
1510
1511 ;Offset PC Bytes Disassembly Source
1512 * = $ffc
1513 >0ffc .align $100
1514 .1000 ee 19 d0 inc $d019 irq inc $d019
1515 >1003 ea .align 4, $ea
1516 .1004 69 01 adc #$01 loop adc #1
1517
1518 When alignment is done within named structures then it's relative to the
1519 start of the structure. This means the structure layout will be always the
1520 same independent which address it's instantiated at. Anonymous structures
1521 do not change the way the alignment works.
1522
1523Dumping data
1524
1525Storing numeric values
1526
1527Multi byte numeric data is stored in the little-endian order, which is the
1528natural byte order for 65xx processors. Numeric ranges are enforced depending
1529on the directives used.
1530
1531When using lists or tuples their content will be used one by one. Uninitialized
1532data (`?') creates holes of different sizes. Character string constants are
1533converted using the current encoding.
1534
1535Please note that multi character strings usually don't fit into 8 bits and
1536therefore the .byte directive is not appropriate for them. Use .text instead
1537which accepts strings of any length.
1538
1539.byte <expression>[, <expression>, ...]
1540 Create bytes from 8 bit unsigned constants (0-255)
1541.char <expression>[, <expression>, ...]
1542 Create bytes from 8 bit signed constants (-128-127)
1543
1544 >1000 ff 03 .byte 255, $03
1545 >1002 41 .byte "a"
1546 >1003 .byte ? ; reserve 1 byte
1547 >1004 fd .char -3
1548 ;Store 4.4 signed fixed point constants
1549 >1005 c8 34 32 .char (-3.5, 3.25, 3.125) * 1p4
1550 ;Compact computed jumps using self modifying code
1551 .1008 bd 0f 10 lda $1010,x lda jumps,x
1552 .100b 8d 0e 10 sta $100f sta smod+1
1553 .100e d0 fe bne $100e smod bne *
1554 ;Routines nearby (-128-127 bytes)
1555 >1010 23 49 jumps .char (routine1, routine2)-smod-2
1556
1557.word <expression>[, <expression>, ...]
1558 Create bytes from 16 bit unsigned constants (0-65535)
1559.sint <expression>[, <expression>, ...]
1560 Create bytes from 16 bit signed constants (-32768-32767)
1561
1562 >1000 42 23 55 45 .word $2342, $4555
1563 >1004 .word ? ; reserve 2 bytes
1564 >1006 eb fd 51 11 .sint -533, 4433
1565 ;Store 8.8 signed fixed point constants
1566 >100a 80 fc 40 03 20 03 .sint (-3.5, 3.25, 3.125) * 1p8
1567 .1010 bd 19 10 lda $1019,x lda texts,x
1568 .1013 bc 1a 10 ldy $101a,x ldy texts+1,x
1569 .1016 4c 1e ab jmp $ab1e jmp $ab1e
1570 >1019 33 10 59 10 texts .word text1, text2
1571
1572.addr <expression>[, <expression>, ...]
1573 Create 16 bit address constants for addresses (in current program bank)
1574.rta <expression>[, <expression>, ...]
1575 Create 16 bit return address constants for addresses (in current program
1576 bank)
1577
1578 * = $12000
1579 .012000 7c 03 20 jmp ($012003,x) jmp (jumps,x)
1580 >012003 50 20 32 03 92 15 jumps .addr $12050, routine1, routine2
1581 ;Computed jumps by using stack (current bank)
1582 * = $103000
1583 .103000 bf 0c 30 10 lda $10300c,x lda rets+1,x
1584 .103004 48 pha pha
1585 .103005 bf 0b 30 10 lda $10300b,x lda rets,x
1586 .103009 48 pha pha
1587 .10300a 60 rts rts
1588 >10300b ff ef a1 36 f3 42 rets .rta $10f000, routine1, routine2
1589
1590.long <expression>[, <expression>, ...]
1591 Create bytes from 24 bit unsigned constants (0-16777215)
1592.lint <expression>[, <expression>, ...]
1593 Create bytes from 24 bit signed constants (-8388608-8388607)
1594
1595 >1000 56 34 12 .long $123456
1596 >1003 .long ? ; reserve 3 bytes
1597 >1006 eb fd ff 51 11 00 .lint -533, 4433
1598 ;Store 8.16 signed fixed point constants
1599 >100c 5d 8f fc 66 66 03 1e 85 .lint (-3.44, 3.4, 3.52) * 1p16
1600 >1014 03
1601 ;Computed long jumps with jump table (65816)
1602 .1015 bd 2a 10 lda $102a,x lda jumps,x
1603 .1018 8d 11 03 sta $0311 sta ind
1604 .101b bd 2b 10 lda $102b,x lda jumps+1,x
1605 .101e 8d 12 03 sta $0312 sta ind+1
1606 .1021 bd 2c 10 lda $102c,x lda jumps+2,x
1607 .1024 8d 13 03 sta $0313 sta ind+2
1608 .1027 dc 11 03 jmp [$0311] jmp [ind]
1609 >102a 32 03 01 92 05 02 jumps .long routine1, routine2
1610
1611.dword <expression>[, <expression>, ...]
1612 Create bytes from 32 bit constants (0-4294967295)
1613.dint <expression>[, <expression>, ...]
1614 Create bytes from 32 bit signed constants (-2147483648-2147483647)
1615
1616 >1000 78 56 34 12 .dword $12345678
1617 >1004 .dword ? ; reserve 4 bytes
1618 >1008 5d 7a 79 e7 .dint -411469219
1619 ;Store 16.16 signed fixed point constants
1620 >100c 5d 8f fc ff 66 66 03 00 .dint (-3.44, 3.4, 3.52) * 1p16
1621 >1014 1e 85 03 00
1622
1623Storing string values
1624
1625The following directives store strings of characters, bytes or bits as bytes.
1626Small numeric constants can be mixed in to represent single byte control
1627characters.
1628
1629When using lists or tuples their content will be used one by one. Uninitialized
1630data (`?') creates byte sized holes. Character string constants are converted
1631using the current encoding.
1632
1633.text <expression>[, <expression>, ...]
1634 Assemble strings into 8 bit bytes.
1635
1636 >1000 4f 45 d5 .text "oeU"
1637 >1003 4f 45 d5 .text 'oeU'
1638 >1006 17 33 .text 23, $33 ; bytes
1639 >1008 0d 0a .text $0a0d ; $0d, $0a, little endian!
1640 >100a 1f .text %00011111; more bytes
1641
1642.fill <length>[, <fill>]
1643 Reserve space (using uninitialized data), or fill with repeated bytes.
1644
1645 >1000 .fill $100 ;no fill, just reserve $100 bytes
1646 >1100 00 00 00 .fill $4000, 0 ;16384 bytes of 0
1647 ...
1648 >5100 55 aa 55 .fill 8000, [$55, $aa];8000 bytes of alternating $55, $aa
1649 ...
1650 >7040 ff ff ff .fill $7100 - *, $ff;fill until $7100 with $ff
1651 ...
1652
1653.shift <expression>[, <expression>, ...]
1654 Assemble strings of 7 bit bytes and mark the last byte by setting it's most
1655 significant bit.
1656
1657 Any byte which already has the most significant bit set will cause an
1658 error. The last byte can't be uninitialized or missing of course.
1659
1660 The naming comes from old TASM and is a reference to setting the high bit
1661 of alphabetic letters which results in it's uppercase version in PETSCII.
1662
1663 .1000 a2 00 ldx #$00 ldx #0
1664 .1002 bd 10 10 lda $1010,x loop lda txt,x
1665 .1005 08 php php
1666 .1006 29 7f and #$7f and #$7f
1667 .1008 20 d2 ff jsr $ffd2 jsr $ffd2
1668 .100b e8 inx inx
1669 .100c 28 plp plp
1670 .100d 10 f3 bpl $1002 bpl loop
1671 .100f 60 rts rts
1672 >1010 53 49 4e 47 4c 45 20 53 txt .shift "single", 32, "string"
1673 >1018 54 52 49 4e c7
1674
1675.shiftl <expression>[, <expression>, ...]
1676 Assemble strings of 7 bit bytes shifted to the left once with the last
1677 byte's least significant bit set.
1678
1679 Any byte which already has the most significant bit set will cause an error
1680 as this is cut off on shifting. The last byte can't be uninitialized or
1681 missing of course.
1682
1683 The naming is a reference to left shifting.
1684
1685 .1000 a2 00 ldx #$00 ldx #0
1686 .1002 bd 0d 10 lda $100d,x loop lda txt,x
1687 .1005 4a lsr a lsr
1688 .1006 9d 00 04 sta $0400,x sta $400,x ;screen memory
1689 .1009 e8 inx inx
1690 .100a 90 f6 bcc $1002 bcc loop
1691 .100c 60 rts rts
1692 .enc "screen"
1693 >100d a6 92 9c 8e 98 8a 40 a6 .shiftl "single", 32, "string"
1694 >1015 a8 a4 92 9c 8f txt .enc "none"
1695
1696.null <expression>[, <expression>, ...]
1697 Same as .text, but adds a zero byte to the end. An existing zero byte is an
1698 error as it'd cause a false end marker.
1699
1700 .1000 a9 07 lda #$07 lda #<txt
1701 .1002 a0 10 ldy #$10 ldy #>txt
1702 .1004 20 1e ab jsr $ab1e jsr $ab1e
1703 >1007 53 49 4e 47 4c 45 20 53 txt .null "single", 32, "string"
1704 >100f 54 52 49 4e 47 00
1705
1706.ptext <expression>[, <expression>, ...]
1707 Same as .text, but prepend the number of bytes in front of the string
1708 (pascal style string). Therefore it can't do more than 255 bytes.
1709
1710 .1000 a9 1d lda #$1d lda #<txt
1711 .1002 a2 10 ldx #$10 ldx #>txt
1712 .1004 20 08 10 jsr $1008 jsr print
1713 .1007 60 rts rts
1714
1715 .1008 85 fb sta $fb print sta $fb
1716 .100a 86 fc stx $fc stx $fc
1717 .100c a0 00 ldy #$00 ldy #0
1718 .100e b1 fb lda ($fb),y lda ($fb),y
1719 .1010 f0 0a beq $101c beq null
1720 .1012 aa tax tax
1721 .1013 c8 iny - iny
1722 .1014 b1 fb lda ($fb),y lda ($fb),y
1723 .1016 20 d2 ff jsr $ffd2 jsr $ffd2
1724 .1019 ca dex dex
1725 .101a d0 f7 bne $1013 bne -
1726 .101c 60 rts null rts
1727 >101d 0d 53 49 4e 47 4c 45 20 txt .ptext "single", 32, "string"
1728 >1025 53 54 52 49 4e 47
1729
1730Text encoding
1731
173264tass supports sources written in UTF-8, UTF-16 (be/le) and RAW 8 bit
1733encoding. To take advantage of this capability custom encodings can be defined
1734to map Unicode characters to 8 bit values in strings.
1735
1736.enc "<name>"
1737 Selects text encoding, predefined encodings are `none' and `screen' (screen
1738 code), anything else is user defined. All user encodings start without any
1739 character or escape definitions, add some as required.
1740
1741 .enc "screen";screen code mode
1742 >1000 13 03 12 05 05 0e 20 03 .text "screen codes"
1743 >1008 0f 04 05 13
1744 .100c c9 15 cmp #$15 cmp #"u" ;compare screen code
1745 .enc "none" ;normal mode again
1746 .100e c9 55 cmp #$55 cmp #"u" ;compare PETSCII
1747
1748.cdef <start>, <end>, <coded> [, <start>, <end>, <coded>, ...]
1749.cdef "<start><end>", <coded> [, "<start><end>", <coded>, ...]
1750 Assigns characters in a range to single bytes.
1751
1752 This is a simple single character to byte translation definition. It is
1753 applied to a range as characters and bytes are usually assigned
1754 sequentially. The start and end positions are Unicode character codes
1755 either by numbers or by typing them. Overlapping ranges are not allowed.
1756
1757 .enc "ascii" ;define an ascii encoding
1758 .cdef " ~", 32 ;identity for printable
1759
1760.edef "<escapetext>", <value> [, "<escapetext>", <value>, ...]
1761 Assigns strings to byte sequences as a translated value.
1762
1763 When these substrings are found in a text they are replaced by bytes
1764 defined here. When strings with common prefixes are used the longest match
1765 wins. Useful for defining non-typeable control code aliases, or as a simple
1766 tokenizer.
1767
1768 .enc "petscii" ;define an ascii->petscii encoding
1769 .cdef " @", 32 ;characters
1770 .cdef "AZ", $c1
1771 .cdef "az", $41
1772 .cdef "[[", $5b
1773 .cdef "??", $5c
1774 .cdef "]]", $5d
1775 .cdef "??", $5e
1776 .cdef $2190, $2190, $1f;left arrow
1777
1778 .edef "\n", 13 ;one byte control codes
1779 .edef "{clr}", 147
1780 .edef "{crlf}", [13, 10];two byte control code
1781 .edef "<nothing>", [];replace with no bytes
1782
1783>1000 93 d4 45 58 54 20 49 4e .text "{clr}Text in PETSCII\n"
1784>1008 20 d0 c5 d4 d3 c3 c9 c9 0d
1785
1786Structured data
1787
1788Structures and unions can be defined to create complex data types. The offset
1789of fields are available by using the definition's name. The fields themselves
1790by using the instance name.
1791
1792The initialization method is very similar to macro parameters, the difference
1793is that unset parameters always return uninitialized data (`?') instead of an
1794error.
1795
1796Structure
1797
1798Structures are for organizing sequential data, so the length of a structure is
1799the sum of lengths of all items.
1800
1801.struct [<name>][=<default>]][, [<name>][=<default>] ...]
1802 Begins a structure block
1803.ends [<result>][, <result> ...]
1804.endstruct [<result>][, <result> ...]
1805 Ends a structure block
1806
1807 Structure definition, with named parameters and default values
1808
1809.dstruct <name>[, <initialization values>]
1810.<name> [<initialization values>]
1811 Create instance of structure with initialization values
1812
1813 .struct ;anonymous structure
1814x .byte 0 ;labels are visible
1815y .byte 0 ;content compiled here
1816 .endstruct ;useful inside unions
1817
1818nn_s .struct col, row;named structure
1819x .byte \col ;labels are not visible
1820y .byte \row ;no content is compiled here
1821 .endstruct ;it's just a definition
1822
1823nn .dstruct nn_s, 1, 2;structure instance, content here
1824
1825 lda nn.x ;direct field access
1826 ldy #nn_s.x ;get offset of field
1827 lda nn,y ;and use it indirectly
1828
1829Union
1830
1831Unions can be used for overlapping data as the compile offset and program
1832counter remains the same on each line. Therefore the length of a union is the
1833length of it's longest item.
1834
1835.union [<name>][=<default>]][, [<name>][=<default>] ...]
1836 Begins a union block
1837.endu
1838.endunion
1839 Ends a union block
1840
1841 Union definition, with named parameters and default values
1842
1843.dunion <name>[, <initialization values>]
1844.<name> [<initialization values>]
1845 Create instance of union with initialization values
1846
1847 .union ;anonymous union
1848x .byte 0 ;labels are visible
1849y .word 0 ;content compiled here
1850 .endunion
1851
1852nn_u .union ;named union
1853x .byte ? ;labels are not visible
1854y .word \1 ;no content is compiled here
1855 .endunion ;it's just a definition
1856
1857nn .dunion nn_u, 1 ;union instance here
1858
1859 lda nn.x ;direct field access
1860 ldy #nn_u.x ;get offset of field
1861 lda nn,y ;and use it indirectly
1862
1863Combined use of structures and unions
1864
1865The example below shows how to define structure to a binary include.
1866
1867 .union
1868 .binary "pic.drp", 2
1869 .struct
1870color .fill 1024
1871screen .fill 1024
1872bitmap .fill 8000
1873backg .byte ?
1874 .endstruct
1875 .endunion
1876
1877Anonymous structures and unions in combination with sections are useful for
1878overlapping memory assignment. The example below shares zero page allocations
1879for two separate parts of a bigger program. The common subroutine variables are
1880assigned after in the `zp' section.
1881
1882* = $02
1883 .union ;spare some memory
1884 .struct
1885 .dsection zp1 ;declare zp1 section
1886 .endstruct
1887 .struct
1888 .dsection zp2 ;declare zp2 section
1889 .endstruct
1890 .endunion
1891 .dsection zp ;declare zp section
1892
1893Macros
1894
1895Macros can be used to reduce typing of frequently used source lines. Each
1896invocation is a copy of the macro's content with parameter references replaced
1897by the parameter texts.
1898
1899.segment [<name>][=<default>]][, [<name>][=<default>] ...]
1900 Start of segment block
1901.endsegment [<result>][, <result> ...]
1902 End of segment block
1903
1904 Copies the code segment as it is, so symbols can be used from outside, but
1905 this also means multiple use will result in double defines unless anonymous
1906 labels are used.
1907
1908.macro [<name>][=<default>]][, [<name>][=<default>] ...]
1909 Start of macro block
1910.endmacro [<result>][, <result> ...]
1911 End of macro block
1912
1913 The code is enclosed in it's own block so symbols inside are
1914 non-accessible, unless a label is prefixed at the place of use, then local
1915 labels can be accessed through that label.
1916
1917#<name> [<param>][[,][<param>] ...]
1918.<name> [<param>][[,][<param>] ...]
1919 Invoke the macro after `#' or `.' with the parameters. Normally the name of
1920 the macro is used, but it can be any expression.
1921.endm [<result>][, <result> ...]
1922 Closing directive of .macro and .segment for compatibility.
1923
1924;A simple macro
1925copy .macro
1926 ldx #size(\1)
1927lp lda \1,x
1928 sta \2,x
1929 dex
1930 bpl lp
1931 .endmacro
1932
1933 #copy label, $500
1934
1935;Use macro as an assembler directive
1936lohi .macro
1937lo .byte <(\@)
1938hi .byte >(\@)
1939 .endmacro
1940
1941var .lohi 1234, 5678
1942
1943 lda var.lo,y
1944 ldx var.hi,y
1945
1946Parameter references
1947
1948The first 9 parameters can be referenced by `\1'-`\9'. The entire parameter
1949list including separators is `\@'.
1950
1951name .macro
1952 lda #\1 ;first parameter 23+1
1953 .endmacro
1954
1955 #name 23+1 ;call macro
1956
1957Parameters can be named, and it's possible to set a default value after an
1958equal sign which is used as a replacement when the parameter is missing.
1959
1960These named parameters can be referenced by \name or \{name}. Names must match
1961completely, if unsure use the quoted name reference syntax.
1962
1963name .macro first, b=2, , last
1964 lda #\first ;first parameter
1965 lda #\b ;second parameter
1966 lda #\3 ;third parameter
1967 lda #\last ;fourth parameter
1968 .endmacro
1969
1970 #name 1, , 3, 4 ;call macro
1971
1972Text references
1973
1974In the original turbo assembler normal references are passed by value and can
1975only appear in place of one. Text references on the other hand can appear
1976everywhere and will work in place of e.g. quoted text or opcodes and labels.
1977The first 9 parameters can be referenced as text by @1-@9.
1978
1979name .macro
1980 jsr print
1981 .null "Hello @1!";first parameter
1982 .endm
1983
1984 #name "wth?" ;call macro
1985
1986Custom functions
1987
1988Beyond the built-in functions mentioned earlier it's possible to define custom
1989ones for frequently used calculations.
1990
1991.sfunction [<name>[=<default>], ...][*<name>,] <expression>
1992 Defines a simple function to return the result of a parametrised expression
1993.function <name>[=<default>]][, <name>[=<default>] ...][, *<name>]
1994 Defines a multi line function
1995.endf [<result>][, <result> ...]
1996.endfunction [<result>][, <result> ...]
1997 End of a multi line function
1998#<name> [<param>][[,][<param>] ...]
1999.<name> [<param>][[,][<param>] ...]
2000<name> [<param>][[,][<param>] ...]
2001 Invoke a multi line function like a macro, directive or pseudo instruction
2002
2003Parameters are assigned to variables in the function scope on invocation. The
2004default values are calculated at function definition time only, and these
2005values are used at invocation time when a parameter is missing.
2006
2007Extra parameters are not accepted, unless the last parameter symbol is preceded
2008with a star, in this case these parameters are collected into a tuple.
2009
2010Only those external variables and functions are available which were accessible
2011at the place of definition, but not those at the place of invocation.
2012
2013vicmem .sfunction _font, _scr=0, ((_font >> 10) & $0f) | ((_scr >> 6) & $f0)
2014
2015 lda #vicmem($2000, $0400); calculate constant
2016 sta $d018
2017
2018If a multi line macro is used in an expression only the returned result is
2019used. If multiple values are returned these will form a tuple.
2020
2021If a multi line function is used as macro, directive or pseudo instruction and
2022there's a label in front then the returned value is assigned to it. If nothing
2023is returned then it's used as regular label.
2024
2025mva .function value, target
2026 lda value
2027 sta target
2028 .endfunction
2029
2030 mva #1, label
2031
2032Conditional assembly
2033
2034To prevent parts of source from compiling conditional constructs can be used.
2035This is useful when multiple slightly different versions needs to be compiled
2036from the same source.
2037
2038Anonymous labels are still recognized in the non-compiling parts even if they
2039won't get defined. This ensures consistent relative referencing across
2040conditionally compiled areas with such labels.
2041
2042If, else if, else
2043
2044.if <condition>
2045 Compile if condition is true
2046.elsif <condition>
2047 Compile if previous conditions were not met and the condition is true
2048.else
2049 Compile if previous conditions were not met
2050.ifne <value>
2051 Compile if value is not zero
2052.ifeq <value>
2053 Compile if value is zero
2054.ifpl <value>
2055 Compile if value is greater or equal zero
2056.ifmi <value>
2057 Compile if value is less than zero
2058
2059 The .ifne, .ifeq, .ifpl and .ifmi directives exists for compatibility only,
2060 in practice it's better to use comparison operators instead.
2061
2062 .if wait==2 ;2 cycles
2063 nop
2064 .elsif wait==3 ;3 cycles
2065 bit $ea
2066 .elsif wait==4 ;4 cycles
2067 bit $eaea
2068 .else ;else 5 cycles
2069 inc $2
2070 .endif
2071
2072.fi
2073.endif
2074 End of conditional compilation.
2075
2076Switch, case, default
2077
2078Similar to the .if, .elsif, .else, .endif construct, but the compared value
2079needs to be written only once in the switch statement.
2080
2081.switch <expression>
2082 Evaluate expression and remember it
2083.case <expression>[, <expression> ...]
2084 Compile if the previous conditions were all skipped and one of the values
2085 equals
2086.default
2087 Compile if the previous conditions were all skipped
2088
2089 .switch wait
2090 .case 2 ;2 cycles
2091 nop
2092 .case 3 ;3 cycles
2093 bit $ea
2094 .case 4 ;4 cycles
2095 bit $eaea
2096 .default ;else 5 cycles
2097 inc $2
2098 .endswitch
2099
2100.endswitch
2101 End of .switch conditional compilation block.
2102
2103Comment
2104
2105.comment
2106 Never compile.
2107
2108 .comment
2109 lda #1 ;this won't be compiled
2110 sta $d020
2111 .endcomment
2112
2113.endc
2114.endcomment
2115 End of .comment block.
2116
2117Repetitions
2118
2119The following directives are used to repeat code or data.
2120
2121The regular non-scoped variants cover most cases except when normal labels are
2122required as those will be double defined.
2123
2124Scoped variants (those starting with the letter b) create a new scope for each
2125iteration. This allows normal labels without collision but it's a bit more
2126resource intensive.
2127
2128If the scoped variant is prefixed with a label then the list of individual
2129scopes for each iteration will be assigned to it. This allows accessing labels
2130within.
2131
2132.for [<assignment>], [<condition>], [<assignment>]
2133.bfor [<assignment>], [<condition>], [<assignment>]
2134 Assign initial value, loop while the condition is true and modify value.
2135
2136 First a variable is set, usually this is used for counting. This is
2137 optional, the variable may be set already before the loop.
2138
2139 Then the condition is checked and the enclosed lines are compiled if it's
2140 true. If there's no condition then it's an infinite loop and .break must be
2141 used to terminate it.
2142
2143 After an iteration the second assignment is calculated, usually it's
2144 updating the loop counter variable. This is optional as well.
2145
2146 ldx #0
2147 lda #32
2148 lp .for ue := $400, ue < $800, ue += $100
2149 sta ue,x ;do $400, $500, $600 and $700
2150 .endfor
2151 dex
2152 bne lp
2153
2154.for <variable>[, <variable>, ...] in <expression>
2155.bfor <variable>[, <variable>, ...] in <expression>
2156 Assign variable(s) to values in sequence one-by-one in order.
2157
2158 The expression is usually the range function or some sort of list.
2159
2160 .for col in 0, 11, 12, 15, 1
2161 lda #col ;0, 11, 12, 15 and 1
2162 sta $d020
2163 .endfor
2164
2165.endfor
2166 End of a .for or .bfor loop block
2167.rept <expression>
2168.brept <expression>
2169 Repeat enclosed lines the specified number of times.
2170
2171 .rept 100
2172 - inx
2173 bne -
2174 .endrept
2175
2176 lst .brept 100 ;each iteration into a tuple
2177 label jmp label ;not a duplicate definition
2178 .endrept
2179 jmp lst[5].label ;use label of 6th iteration
2180
2181.endrept
2182 End of a .rept or .brept block
2183.while <condition>
2184.bwhile <condition>
2185 Repeat enclosed lines until the condition holds.
2186
2187 Works as expected however the scoped variant might be tricky to use as
2188 variables in the condition might not be in the same scope as the loop body.
2189
2190.endwhile
2191 End of a .while or .bwhile loop block
2192.break
2193 Exit current repetition loop immediately.
2194.breakif <condition>
2195 Exit current repetition loop immediately if the condition holds.
2196
2197 It's a shorthand for a .if, .break, .endif sequence.
2198
2199.continue
2200 Continue current repetition loop's next iteration.
2201.continueif <condition>
2202 Continue current repetition loop's next iteration if the condition holds.
2203
2204 It's a shorthand for a .if, .continue, .endif sequence.
2205
2206.next
2207 Closing directive of .for, .bfor, .rept, .brept, .while and .bwhile loop
2208 for compatibility.
2209.lbl
2210 Creates a special jump label that can be referenced by .goto
2211.goto <labelname>
2212 Causes assembler to continue assembling from the jump label. No forward
2213 references of course, handle with care. Should only be used in classic TASM
2214 sources for creating loops.
2215
2216 i .var 100
2217 loop .lbl
2218 nop
2219 i .var i - 1
2220 .ifne i
2221 .goto loop ;generates 100 nops
2222 .endif ;the hard way ;)
2223
2224Including files
2225
2226Longer sources are usually separated into multiple files for easier handling.
2227Precomputed binary data can also be included directly without converting it
2228into source code first.
2229
2230Search path is relative to the location of current source file. If it's not
2231found there the include search path is consulted for further possible
2232locations.
2233
2234To make your sources portable please always use forward slashes (/) as a
2235directory separator and use lower/uppercase consistently in file names!
2236
2237.include <filename>
2238 Include source file here.
2239.binclude <filename>
2240 Include source file here in it's local block. If the directive is prefixed
2241 with a label then all labels are local and are accessible through that
2242 label only, otherwise not reachable at all.
2243
2244
2245 .include "macros.asm" ;include macros
2246 menu .binclude "menu.asm" ;include in a block
2247 jmp menu.start
2248
2249.binary <filename>[, <offset>[, <length>]]
2250 Include raw binary data from file.
2251
2252 By using offset and length it's possible to break out chunks of data from a
2253 file separately, like bitmap and colors for example. Negative offsets are
2254 calculated from the end of file.
2255
2256 .binary "stuffz.bin" ;simple include, all bytes
2257 .binary "stuffz.bin", 2 ;skip start address
2258 .binary "stuffz.bin", 2, 1000;skip start address, 1000 bytes max
2259
2260Scopes
2261
2262Scopes may contain symbols or further nested scopes. The same symbol name can
2263be reused as long as it's in a different scope.
2264
2265A symbol is looked up in the local scope first. If it's a non-local symbol then
2266parent scopes and the global scope may be searched in addition. This means that
2267a symbol in a parent or global scope may be `shadowed'.
2268
2269Symbols of a named scope can be looked up using the `.' operator. The searched
2270symbol stands on the right and it's looked up in the scope on the left. More
2271than one symbol may be looked up at the same time and the result will be a list
2272or tuple.
2273
2274 lda #0
2275 sta vic.sprite.enable
2276; same as .byte colors.red, colors.green, colors.blue
2277ctable .byte colors.(red, green, blue)
2278
2279.proc
2280 Start of a procedure block
2281.pend
2282.endproc
2283 End of a procedure block
2284
2285 If the symbol in front is not referenced anywhere then the enclosed source
2286 won't be compiled.
2287
2288 Symbols inside are enclosed in a scope and are accessible through the
2289 symbol of the procedure using the dot notation. This forces compilation of
2290 the whole procedure of course.
2291
2292 ize .proc
2293 nop
2294 cucc nop
2295 .endproc
2296
2297 jsr ize
2298 jmp ize.cucc
2299
2300 The `compilation only if used' behaviour of .proc eases the building of
2301 `libraries' from a collection of subroutines and tables where not
2302 everything is needed all the time.
2303
2304 Alternative dead-code reduction techniques I encountered:
2305
2306 Separate source files
2307 This potentially results in a lot of small files and manually managed
2308 include directives. This is popular on external linker based systems
2309 where object files may be excluded if unused.
2310 Conditional compilation
2311 Few larger files with conditional compilation directives all over the
2312 place to exclude or include various parts. The source which does the
2313 include manually declares somewhere what's actually needed or not.
2314 There may be a lot of options if it's fine grained enough.
2315 Wrap parts with macros
2316 If a part is needed then a single macro call is placed somewhere to
2317 `include' that part. Much better than conditional compilation but these
2318 macro calls still need to be manually managed.
2319
2320.block
2321 Block scoping area start
2322.bend
2323.endblock
2324 Block scoping area end
2325
2326 All symbols inside a block are enclosed in a scope. If the block had a
2327 symbol then local symbols are accessible through that using the dot
2328 notation.
2329
2330 .block
2331 inc count + 1
2332 count ldx #0
2333 .bend
2334
2335.namespace [<symbol>]
2336 Namespace area start
2337.endn
2338.endnamespace
2339 Namespace area end
2340
2341 This directive either creates a new scope (if used without a parameter) or
2342 activates the one in the parameter.
2343
2344 The scope can be assigned to a symbol in front of the directive so that it
2345 can be reactivated later.
2346
2347 This enabled label definitions into the same scope in different files.
2348
2349.weak
2350.endweak
2351 Weak symbol area
2352
2353 Any symbols defined inside can be overridden by `stronger' symbols in the
2354 same scope from outside. Can be nested as necessary.
2355
2356 This gives the possibility of giving default values for symbols which might
2357 not always exist without resorting to .ifdef/.ifndef or similar directives
2358 in other assemblers.
2359
2360 symbol = 1 ;stronger symbol than the one below
2361 .weak
2362 symbol = 0 ;default value if the one above does not exists
2363 .endweak
2364 .if symbol ;almost like an .ifdef ;)
2365
2366 Other use of weak symbols might be in included libraries to change default
2367 values or replace stub functions and data structures.
2368
2369 If these stubs are defined using .proc/.endproc then their default
2370 implementations will not even exists in the output at all when a stronger
2371 symbol overrides them.
2372
2373 Multiple definition of a symbol with the same `strength' in the same scope
2374 is of course not allowed and it results in double definition error.
2375
2376 Please note that .ifdef/.ifndef directives are left out from 64tass for of
2377 technical reasons, so don't wait for them to appear anytime soon.
2378
2379.with <symbol>
2380.endwith
2381 Namespace access
2382
2383 This directive is similar to .namespace but it gives access to another
2384 scope's variables without leaving the current scope. May be useful to allow
2385 a short hand access in some situations.
2386
2387 It's advised to use the -Wshadow command line option to warn about any
2388 unexpected symbol ambiguity.
2389
2390Sections
2391
2392Sections can be used to collect data or code into separate memory areas without
2393moving source code lines around. This is achieved by having separate compile
2394offset and program counters for each defined section.
2395
2396.section <name>
2397 Starts a segment block
2398.send [<name>]
2399.endsection [<name>]
2400 Ends a segment block
2401
2402 Defines a section fragment. The name at .send must match but it's optional.
2403
2404.dsection <name>
2405 Collect the section fragments here.
2406
2407All .section fragments are compiled to the memory area allocated by the
2408.dsection directive. Compilation happens as the code appears, this directive
2409only assigns enough space to hold all the content in the section fragments.
2410
2411The space used by section fragments is calculated from the difference of
2412starting compile offset and the maximum compile offset reached. It is possible
2413to manipulate the compile offset in fragments, but putting code before the
2414start of .dsection is not allowed.
2415
2416* = $02
2417 .dsection zp ;declare zero page section
2418 .cerror * > $30, "Too many zero page variables"
2419
2420* = $334
2421 .dsection bss ;declare uninitialized variable section
2422 .cerror * > $400, "Too many variables"
2423
2424* = $0801
2425 .dsection code ;declare code section
2426 .cerror * > $1000, "Program too long!"
2427
2428* = $1000
2429 .dsection data ;declare data section
2430 .cerror * > $2000, "Data too long!"
2431;--------------------
2432 .section code
2433 .word ss, 2005
2434 .null $9e, format("%4d", start)
2435ss .word 0
2436
2437start sei
2438 .section zp ;declare some new zero page variables
2439p2 .addr ? ;a pointer
2440 .send zp
2441 .section bss ;new variables
2442buffer .fill 10 ;temporary area
2443 .send bss
2444
2445 lda (p2),y
2446 lda #<label
2447 ldy #>label
2448 jsr print
2449
2450 .section data ;some data
2451label .null "message"
2452 .send data
2453
2454 jmp error
2455 .section zp ;declare some more zero page variables
2456p3 .addr ? ;a pointer
2457 .send zp
2458 .send code
2459
2460The compiled code will look like:
2461
2462>0801 0b 08 d5 07 .word ss, 2005
2463>0805 9e 32 30 36 31 00 .null $9e, format("%4d", start)
2464>080b 00 00 ss .word 0
2465
2466.080d 78 start sei
2467
2468>0002 p2 .addr ? ;a pointer
2469>0334 buffer .fill 10 ;temporary area
2470
2471.080e b1 02 lda (p2),y
2472.0810 a9 00 lda #<label
2473.0812 a0 10 ldy #>label
2474.0814 20 1e ab jsr print
2475
2476>1000 6d 65 73 73 61 67 65 00 label .null "message"
2477
2478.0817 4c e2 fc jmp error
2479
2480>0004 p2 .addr ? ;a pointer
2481
2482Sections can form a hierarchy by nesting a .dsection into another section. The
2483section names must only be unique within a section but can be reused otherwise.
2484Parent section names are visible for children, siblings can be reached through
2485parents.
2486
2487In the following example the included sources don't have to know which `code'
2488and `data' sections they use, while the `bss' section is shared for all banks.
2489
2490;First 8K bank at the beginning, PC at $8000
2491* = $0000
2492 .logical $8000
2493 .dsection bank1
2494 .cerror * > $a000, "Bank1 too long"
2495 .here
2496
2497bank1 .block ;Make all symbols local
2498 .section bank1
2499 .dsection code ;Code and data sections in bank1
2500 .dsection data
2501 .section code ;Pre-open code section
2502 .include "code.asm"; see below
2503 .include "iter.asm"
2504 .send code
2505 .send bank1
2506 .bend
2507
2508;Second 8K bank at $2000, PC at $8000
2509* = $2000
2510 .logical $8000
2511 .dsection bank2
2512 .cerror * > $a000, "Bank2 too long"
2513 .here
2514
2515bank2 .block ;Make all symbols local
2516 .section bank2
2517 .dsection code ;Code and data sections in bank2
2518 .dsection data
2519 .section code ;Pre-open code section
2520 .include "scr.asm"
2521 .send code
2522 .send bank2
2523 .bend
2524
2525;Common data, avoid initialized variables here!
2526* = $c000
2527 .dsection bss
2528 .cerror * > $d000, "Too much common data"
2529;------------- The following is in "code.asm"
2530code sei
2531
2532 .section bss ;Common data section
2533buffer .fill 10
2534 .send bss
2535
2536 .section data ;Data section (in bank1)
2537routine .addr print
2538 .send bss
2539
254065816 related
2541
2542.as
2543.al
2544 Select short (8 bit) or long (16 bit) accumulator immediate constants.
2545
2546 .al
2547 lda #$4322
2548
2549.xs
2550.xl
2551 Select short (8 bit) or long (16 bit) index register immediate constants.
2552
2553 .xl
2554 ldx #$1000
2555
2556.autsiz
2557.mansiz
2558 Select automatic adjustment of immediate constant sizes based on SEP/REP
2559 instructions.
2560
2561 .autsiz
2562 rep #$10 ;implicit .xl
2563 ldx #$1000
2564
2565.databank <expression>
2566 Data bank (absolute) addressing is only used for addresses falling into
2567 this 64 KiB bank. The default is 0, which means addresses in bank zero.
2568
2569 When data bank is switched off only data bank indexed (,b) addresses create
2570 data bank accessing instructions.
2571
2572 .databank $10 ;data bank at $10xxxx
2573 lda $101234 ;results in $ad, $34, $12
2574 .databank ? ;no data bank
2575 lda $1234 ;direct page or long addressing
2576 lda #$1234,b ;results in $ad, $34, $12
2577
2578.dpage <expression>
2579 Direct (zero) page addressing is only used for addresses falling into a
2580 specific 256 byte address range. The default is 0, which is the first page
2581 of bank zero.
2582
2583 When direct page is switched off only the direct page indexed (,d)
2584 addresses create direct page accessing instructions.
2585
2586 .dpage $400 ;direct page $400-$4ff
2587 lda $456 ;results in $a5, $56
2588 .dpage ? ;no direct page
2589 lda $56 ;data bank or long addressing
2590 lda #$56,d ;results in $a5, $56
2591
2592Controlling errors
2593
2594.page
2595 Start of page check block
2596.endp
2597.endpage
2598 End of page check block
2599
2600 Gives an error on page boundary crossing, e.g. for timing sensitive code.
2601
2602 .page
2603 table .byte 0, 1, 2, 3, 4, 5, 6, 7
2604 .endpage
2605
2606.option allow_branch_across_page
2607 Switches error generation on page boundary crossing during relative branch.
2608 Such a condition on 6502 adds 1 extra cycle to the execution time, which
2609 can ruin the timing of a carefully cycle counted code.
2610
2611 .option allow_branch_across_page = 0
2612 ldx #3 ;now this will execute in
2613 - dex ;16 cycles for sure
2614 bne -
2615 .option allow_branch_across_page = 1
2616
2617.error <message> [, <message>, ...]
2618.cerror <condition>, <message> [, <message>, ...]
2619 Exit with error or conditionally exit with error
2620
2621 .error "Unfinished here..."
2622 .cerror * > $1200, "Program too long by ", * - $1200, " bytes"
2623
2624.warn <message> [, <message>, ...]
2625.cwarn <condition>, <message> [, <message>, ...]
2626 Display a warning message always or depending on a condition
2627
2628 .warn "FIXME: handle negative values too!"
2629 .cwarn * > $1200, "This may not work!"
2630
2631Target
2632
2633.cpu <expression>
2634 Selects CPU according to the string argument.
2635
2636 .cpu "6502" ;standard 65xx
2637 .cpu "65c02" ;CMOS 65C02
2638 .cpu "65ce02" ;CSG 65CE02
2639 .cpu "6502i" ;NMOS 65xx
2640 .cpu "65816" ;W65C816
2641 .cpu "65dtv02" ;65dtv02
2642 .cpu "65el02" ;65el02
2643 .cpu "r65c02" ;R65C02
2644 .cpu "w65c02" ;W65C02
2645 .cpu "4510" ;CSG 4510
2646 .cpu "default" ;cpu set on commandline
2647
2648Misc
2649
2650.end
2651 Terminate assembly. Any content after this directive is ignored.
2652.eor <expression>
2653 XOR output with an 8 bit value. Useful for reverse screen code text for
2654 example, or for silly `encryption'.
2655.seed <expression>
2656 Seed the pseudo random number generator with an unsigned integer of maximum
2657 128 bits to make the generated numbers less boring.
2658.var <expression>
2659 Defines a variable identified by the label preceding, which is set to the
2660 value of expression or reference of variable.
2661.assert
2662.check
2663 Do not use these, the syntax will change in next version!
2664
2665Printer control
2666
2667.pron
2668.proff
2669 Turn on or off source listing on part of the file.
2670
2671 .proff ;Don't put filler bytes into listing
2672 * = $8000
2673 .fill $2000, $ff ;Pre-fill ROM area
2674 .pron
2675 * = $8000
2676 .addr reset, restore
2677 .text "CBM80"
2678 reset cld
2679
2680.hidemac
2681.showmac
2682 Ignored for compatibility.
2683
2684-------------------------------------------------------------------------------
2685
2686Pseudo instructions
2687
2688Aliases
2689
2690For better code readability BCC has an alias named BLT (Branch Less Than) and
2691BCS one named BGE (Branch Greater Equal).
2692
2693 cmp #3
2694 blt exit ; less than 3?
2695
2696For similar reasons ASL has an alias named SHL (SHift Left) and LSR one named
2697SHR (SHift Right). This naming however is not very common.
2698
2699The implied variants LSR, ROR, ASL and ROL are a shorthand for LSR A, ROR A,
2700ASL A and ROL A. Using the implied form is considered poor coding style.
2701
2702For compatibility INA and DEA is a shorthand of INC A and DEC A. Therefore
2703there's no `implied' variants like INC or DEC. The full form with the
2704accumulator is preferred.
2705
2706The longer forms of INC X, DEC X, INC Y, DEC Y, INC Z and DEC Z are available
2707for INX, DEX, INY, DEY, INZ and DEZ. For this to work care must be taken to not
2708reuse the `x', `y' and `z' single letter register symbols for other purposes.
2709Same goes for `a' of course.
2710
2711Load instructions with registers are translated to transfer instructions. For
2712example LDA X becomes TXA.
2713
2714Store instructions with registers are translated to transfer instructions, but
2715only if it involves the `s' or `b' registers. For example STX S becomes TXS.
2716
2717Many illegal opcodes have aliases for compatibility as there's no standard
2718naming convention.
2719
2720Always taken branches
2721
2722For writing short code there are some special pseudo instructions for always
2723taken branches. These are automatically compiled as relative branches when the
2724jump distance is short enough and as JMP or BRL when longer.
2725
2726The names are derived from conditional branches and are: GEQ, GNE, GCC, GCS,
2727GPL, GMI, GVC, GVS, GLT and GGE.
2728
2729.0000 a9 03 lda #$03 in1 lda #3
2730.0002 d0 02 bne $0006 gne at ;branch always
2731.0004 a9 02 lda #$02 in2 lda #2
2732.0006 4c 00 10 jmp $1000 at gne $1000 ;branch farther
2733
2734If the branch would skip only one byte then the opposite condition is compiled
2735and only the first byte is emitted. This is now a never executed jump, and the
2736relative distance byte after the opcode is the jumped over byte. If the CPU has
2737long conditional branches (65CE02/4510) then the same method is applied to two
2738byte skips as well.
2739
2740There's a pseudo opcode called GRA for CPUs supporting BRA, which is expanded
2741to BRL (if available) or JMP. A one byte skip will be shortened to a single
2742byte if the CPU has a NOP immediate instruction (R65C02/W65C02).
2743
2744If the branch would not skip anything at all then no code is generated.
2745
2746.0009 geq in3 ;zero length "branch"
2747.0009 18 clc in3 clc
2748.000a b0 bcs gcc at2 ;one byte skip, as bcs
2749.000b 38 sec in4 sec ;sec is skipped!
2750.000c 20 0f 00 jsr $000f at2 jsr func
2751.000f func
2752
2753Please note that expressions like Gxx *+2 or Gxx *+3 are not allowed as the
2754compiler can't figure out if it has to create no code at all, the 1 byte
2755variant or the 2 byte one. Therefore use normal or anonymous labels defined
2756after the jump instruction when jumping forward!
2757
2758Long branches
2759
2760To avoid branch too long errors the assembler also supports long branches. It
2761can automatically convert conditional relative branches to it's opposite and a
2762JMP or BRL. This can be enabled on the command line using the `--long-branch'
2763option.
2764
2765.0000 ea nop nop
2766.0001 b0 03 bcs $0006 bcc $1000 ;long branch (6502)
2767.0003 4c 00 10 jmp $1000
2768.0006 1f 17 03 bbr 1,$17,$000c bbs 1,23,$1000 ;long branch (R65C02)
2769.0009 4c 00 10 jmp $1000
2770.000c d0 04 bne $0012 beq $10000 ;long branch (65816)
2771.000e 5c 00 00 01 jmp $010000
2772.0012 30 03 bmi $0017 bpl $1000 ;long branch (65816)
2773.0014 82 e9 lf brl $1000
2774.0017 ea nop nop
2775
2776Please note that forward jump expressions like Bxx *+130, Bxx *+131 and Bxx
2777*+132 are not allowed as the compiler can't decide between a short/long branch.
2778Of course these destinations can be used, but only with normal or anonymous
2779labels defined after the jump instruction.
2780
2781In the above example extra JMP instructions are emitted for each long branch.
2782This is suboptimal and wasting space if there are several long branches to the
2783same location in close proximity. Therefore the assembler might decide to reuse
2784a JMP for more than one long branch to save space.
2785
2786-------------------------------------------------------------------------------
2787
2788Original turbo assembler compatibility
2789
2790How to convert source code for use with 64tass
2791
2792Currently there are two options, either use `TMPview' by Style to convert the
2793source file directly, or do the following:
2794
2795 * load turbo assembler, start (by SYS 9*4096 or SYS 8*4096 depending on
2796 version)
2797 * <- then l to load a source file
2798 * <- then w to write a source file in PETSCII format
2799 * convert the result to ASCII using petcat (from the vice package)
2800
2801The resulting file should then (with the restrictions below) assemble using the
2802following command line:
2803
280464tass -C -T -a -W -i source.asm -o outfile.prg
2805
2806Differences to the original turbo ass macro on the C64
2807
280864tass is nearly 100% compatible with the original `Turbo Assembler', and
2809supports most of the features of the original `Turbo Assembler Macro'. The
2810remaining notable differences are listed here.
2811
2812Labels
2813
2814The original turbo assembler uses case sensitive labels, use the `
2815--case-sensitive' command line option to enable this behaviour.
2816
2817Expression evaluation
2818
2819There are a few differences which can be worked around by the `
2820--tasm-compatible' command line option. These are:
2821
2822The original expression parser has no operator precedence, but 64tass has. That
2823means that you will have to fix expressions using braces accordingly, for
2824example 1+2*3 becomes (1+2)*3.
2825
2826The following operators used by the original Turbo Assembler are different:
2827
2828 TASM Operator differences
2829. bitwise or, now |
2830: bitwise eor, now ^
2831! force 16 bit address, now @w
2832
2833The default expression evaluation is not limited to 16 bit unsigned numbers
2834anymore.
2835
2836Macros
2837
2838Macro parameters are referenced by `\1'-`\9' instead of using the pound sign.
2839
2840Parameters are always copied as text into the macro and not passed by value as
2841the original turbo assembler does, which sometimes may lead to unexpected
2842behaviour. You may need to make use of braces around arguments and/or
2843references to fix this.
2844
2845Bugs
2846
2847Some versions of the original turbo assembler had bugs that are not reproduced
2848by 64tass, you will have to fix the code instead.
2849
2850In some versions labels used in the first .block are globally available. If you
2851get a related error move the respective label out of the .block.
2852
2853-------------------------------------------------------------------------------
2854
2855Command line options
2856
2857Short command line options consist of `-' and a letter, long options start with
2858`--'.
2859
2860If `--' is encountered then further options are not recognized and are assumed
2861to be file names.
2862
2863Options requiring file names are marked with `<filename>'. A single `-' as name
2864means standard input or output. File name quoting is system specific.
2865
2866Output options
2867
2868-o <filename>, --output <filename>
2869 Place output into <filename>. The default output filename is `a.out'. This
2870 option changes it.
2871
2872 64tass a.asm -o a.prg
2873
2874 This option may be used multiple times to output different sections in
2875 different formats of a single compilation.
2876
2877 For multiple outputs the format options and output section selection must
2878 be placed before this option. The format selection will be unchanged if no
2879 new selection was made but the output section selection must be repeated
2880 for each output. The maximum image size will be the smallest of all
2881 selected formats. Using the same name multiple times is not a good idea.
2882
2883--output-append <filename>
2884 Same as the --output option but appends instead of overwrites.
2885
2886 Normally output files are overwritten but in some cases it's useful to
2887 append them instead.
2888
2889--no-output
2890 No output file will be written.
2891
2892 Useful for test compiles.
2893
2894--output-section <sectionname>
2895 By default all sections go into the output file. Using this option limits
2896 the output to specific section and it's children. This is useful to split a
2897 larger program into several files.
2898
2899 64tass a.asm --output-section main -o main.prg
2900 64tass a.asm --output-section loader -o loader.prg
2901
2902-X, --long-address
2903 Use 3 byte address/length for CBM and nonlinear output instead of 2 bytes.
2904 Also increases the size of raw output to 16 MiB.
2905
2906 64tass --long-address --m65816 a.asm
2907
2908--cbm-prg
2909 Generate CBM format binaries (default)
2910
2911 The first 2 bytes are the little endian address of the first valid byte
2912 (start address). Overlapping blocks are flattened and uninitialized memory
2913 is filled up with zeros. Uninitialized memory before the first and after
2914 the last valid bytes are not saved. Up to 64 KiB or 16 MiB with long
2915 address.
2916
2917 Used for C64 binaries.
2918
2919-b, --nostart
2920 Output raw data without start address.
2921
2922 Overlapping blocks are flattened and uninitialized memory is filled up with
2923 zeros. Uninitialized memory before the first and after the last valid bytes
2924 are not saved. Up to 64 KiB or 16 MiB with long address.
2925
2926 Useful for small ROM files.
2927
2928-f, --flat
2929 Flat address space output mode.
2930
2931 Overlapping blocks are flattened and uninitialized memory is filled up with
2932 zeros. Uninitialized memory after the last valid byte is not saved. Up to
2933 4 GiB.
2934
2935 Useful for creating huge multi bank ROM files. See sections for an example.
2936
2937-n, --nonlinear
2938 Generate nonlinear output file.
2939
2940 Overlapping blocks are flattened. Blocks are saved in sorted order and
2941 uninitialized memory is skipped. Up to 64 KiB or 16 MiB with long address.
2942
2943 Used for linkers and downloading.
2944
2945 64tass --nonlinear a.asm
2946 * = $1000
2947 lda #2
2948 * = $2000
2949 nop
2950
2951 Result of compilation
2952 $02, $00 little endian length, 2 bytes
2953 $00, $10 little endian start $1000
2954 $a9, $02 code
2955 $01, $00 little endian length, 1 byte
2956 $00, $20 little endian start $2000
2957 $ea code
2958 $00, $00 end marker (length=0)
2959
2960--atari-xex
2961 Generate an Atari XEX output file.
2962
2963 Overlapping blocks are kept, continuing blocks are concatenated. Saving
2964 happens in the definition order without sorting, and uninitialized memory
2965 is skipped in the output. Up to 64 KiB.
2966
2967 Used for Atari executables.
2968
2969 64tass --atari-xex a.asm
2970 * = $02e0
2971 .addr start ;run address
2972 * = $2000
2973 start rts
2974
2975 Result of compilation
2976 $ff, $ff header, 2 bytes
2977 $e0, $02 little endian start $02e0
2978 $e1, $02 little endian last byte $02e1
2979 $00, $20 start address word
2980 $00, $20 little endian start $2000
2981 $00, $20 little endian last byte $2000
2982 $60 code
2983
2984--apple2
2985 Generate an Apple II output file (DOS 3.3).
2986
2987 Overlapping blocks are flattened and uninitialized memory is filled up with
2988 zeros. Uninitialized memory before the first and after the last valid bytes
2989 are not saved. Up to 64 KiB.
2990
2991 Used for Apple II executables.
2992
2993 64tass --apple-ii a.asm
2994 * = $0c00
2995 rts
2996
2997 Result of compilation
2998 $00, $0c little endian start $0c00
2999 $01, $00 little endian length $0001
3000 $60 code
3001
3002--intel-hex
3003 Use Intel HEX output file format.
3004
3005 Overlapping blocks are kept, data is stored in the definition order, and
3006 uninitialized areas are skipped. I8HEX up to 64 KiB, I32HEX up to 4 GiB.
3007
3008 Used for EPROM programming or downloading.
3009
3010 64tass --intel-hex a.asm
3011 * = $0c00
3012 rts
3013
3014 Result of compilation:
3015
3016 :010C00006093
3017 :00000001FF
3018
3019--s-record
3020 Use Motorola S-record output file format.
3021
3022 Overlapping blocks are kept, data is stored in the definition order, and
3023 uninitialized memory areas are skipped. S19 up to 64 KiB, S28 up to 16 MiB
3024 and S37 up to 4 GiB.
3025
3026 Used for EPROM programming or downloading.
3027
3028 64tass --s-record a.asm
3029 * = $0c00
3030 rts
3031
3032 Result of compilation:
3033
3034 S1040C00608F
3035 S9030C00F0
3036
3037Operation options
3038
3039-a, --ascii
3040 Use ASCII/Unicode text encoding instead of raw 8-bit
3041
3042 Normally no conversion takes place, this is for backwards compatibility
3043 with a DOS based Turbo Assembler editor, which could create PETSCII files
3044 for 6502tass. (including control characters of course)
3045
3046 Using this option will change the default `none' and `screen' encodings to
3047 map 'a'-'z' and 'A'-'Z' into the correct PETSCII range of $41-$5A and
3048 $C1-$DA, which is more suitable for an ASCII editor. It also adds
3049 predefined petcat style PETSCII literals to the default encodings, and
3050 enables Unicode letters in symbol names.
3051
3052 For writing sources in UTF-8/UTF-16 encodings this option is required!
3053
3054 64tass a.asm
3055
3056 .0000 a9 61 lda #$61 lda #"a"
3057
3058 >0002 31 61 41 .text "1aA"
3059 >0005 7b 63 6c 65 61 72 7d 74 .text "{clear}text{return}more"
3060 >000e 65 78 74 7b 72 65 74 75
3061 >0016 72 6e 7d 6d 6f 72 65
3062
3063 64tass --ascii a.asm
3064
3065 .0000 a9 41 lda #$41 lda #"a"
3066 >0002 31 41 c1 .text "1aA"
3067 >0005 93 54 45 58 54 0d 4d 4f .text "{clear}text{return}more"
3068 >000e 52 45
3069
3070-B, --long-branch
3071 Automatic BXX *+5 JMP xxx. Branch too long messages are usually solved by
3072 manually rewriting them as BXX *+5 JMP xxx. 64tass can do this
3073 automatically if this option is used. BRA is of course not converted.
3074
3075 64tass a.asm
3076 * = $1000
3077 bcc $1233 ;error...
3078
3079 64tass a.asm
3080 * = $1000
3081 bcs *+5 ;opposite condition
3082 jmp $1233 ;as simple workaround
3083
3084 64tass --long-branch a.asm
3085 * = $1000
3086 bcc $1233 ;no error, automatically converted to the above one.
3087
3088-C, --case-sensitive
3089 Make all symbols (variables, opcodes, directives, operators, etc.) case
3090 sensitive. Otherwise everything is case insensitive by default.
3091
3092 64tass a.asm
3093 label nop
3094 Label nop ;double defined...
3095
3096 64tass --case-sensitive a.asm
3097 label nop
3098 Label nop ;Ok, it's a different label...
3099
3100-D <label>=<value>
3101 Command line definition.
3102
3103 Same syntax is allowed as in source files. Be careful with strings, the
3104 shell might eat the quotes unless escaped.
3105
3106 Using hexadecimal numbers might be tricky as the shell might try to expand
3107 them as variables. Either quoting or backslash escaping might help.
3108
3109 In Makefiles all $ signs need to be escaped by doubling them. This needs to
3110 be done over the normal shell escaping. For example `$1000' becomes `\
3111 $$1000'.
3112
3113 64tass -D ii=2 -D var=\"string\" -D FAST:=true a.asm
3114 lda #ii ;result: $a9, $02
3115 FAST :?= false ;define if undefined
3116
3117-q, --quiet
3118 Suppress messages. Disables header and summary messages.
3119
3120 64tass --quiet a.asm
3121
3122-T, --tasm-compatible
3123 Enable TASM compatible operators and precedence
3124
3125 Switches the expression evaluator into compatibility mode. This enables
3126 `.', `:' and `!' operators and disables 64tass specific extensions,
3127 disables precedence handling and forces 16 bit unsigned evaluation (see
3128 `differences to original Turbo Assembler' below)
3129
3130-I <path>
3131 Specify include search path
3132
3133 If an included source or binary file can't be found in the directory of the
3134 source file then this path is tried. More than one directories can be
3135 specified by repeating this option. If multiple matches exist the first one
3136 is used.
3137
3138-M <file>, --dependencies <file>
3139 Specify make rule output file
3140
3141 Writes a dependency rules suitable for `make' from the list of files used
3142 during compilation.
3143
3144 Please choose source file names which are compatible with Makefiles as
3145 there are very little escaping possibilities.
3146
3147--make-phony
3148 Enable phony targets for dependencies
3149
3150 This is useful for automatic dependency generation to avoid missing target
3151 errors on file rename.
3152
3153 The following Makefile uses the rules generated by 64tass (in `.dep') to
3154 achieve automatic dependency tracking:
3155
3156 demo: demo.asm .dep
3157 64tass --make-phony -M.dep $< -o $@
3158
3159 .dep:
3160 -include .dep
3161
3162Diagnostic options
3163
3164Diagnostic message switched start with a `-W' and can have an optional `no-'
3165prefix to disable them. The options below with this prefix are enabled by
3166default, the others are disabled.
3167
3168-E <file>, --error <file>
3169 Specify error output file
3170
3171 Normally compilation errors a written to the standard error output. It's
3172 possible to redirect them to a file or to the standard output by using `-'
3173 as the file name.
3174
3175--error-append <filename>
3176 Same as the --error option but appends instead of overwrites.
3177--no-error
3178 Do not output any error messages, just count them.
3179-w, --no-warn
3180 Suppress warnings.
3181
3182 Disables warnings during compile. For fine grained diagnostic message
3183 suppression see the diagnostic options section.
3184
3185 64tass --no-warn a.asm
3186
3187--no-caret-diag
3188 Suppress displaying of faulty source line and fault position after fault
3189 messages.
3190
3191 This is for cases where the fault log is automatically processed and no one
3192 ever looks at it and therefore there's no point to display the source
3193 lines.
3194
3195 64tass --no-caret-diag a.asm
3196
3197--macro-caret-diag
3198 Restrict source line and fault position display to macro expansions only.
3199
3200 This is for cases where the fault log is processed by an editor which also
3201 displays the compilation output somewhere. Only lines which are the result
3202 of macro processing will be output to aid debugging. Those which would just
3203 duplicate what's in the source editor window will be not.
3204
3205 64tass --macro-caret-diag a.asm
3206
3207-Wall
3208 Enable most diagnostic warnings, except those individually disabled. Or
3209 with the `no-' prefix disable all except those enabled.
3210-Werror
3211 Make all diagnostic warnings to an error, except those individually set to
3212 a warning.
3213-Werror=<name>
3214 Change a diagnostic warning to an error.
3215
3216 For example `-Werror=implied-reg' makes this check an error. The
3217 `-Wno-error=' variant is useful with `-Werror' to set some to warnings.
3218
3219-Walias
3220 Warns about alias opcodes.
3221
3222 There are several opcodes for the same task, especially for the "6502i"
3223 target.
3224
3225-Waltmode
3226 Warn about alternative address modes.
3227
3228 Sometimes alternative addressing modes are used as the fitting one is not
3229 available. For example there's no lda direct page y so instead data bank y
3230 is used with a warning.
3231
3232-Wbranch-page
3233 Warns if a branch is crossing a page.
3234
3235 Page crossing branches execute with a penalty cycle. This option helps to
3236 locate them easily.
3237
3238-Wcase-symbol
3239 Warn if symbol letter case is used inconsistently.
3240
3241 This option can be used to enforce letter case matching of symbols in case
3242 insensitive mode. This gives similar results to the case sensitive mode
3243 (symbols must match exactly) with the main difference of disallowing symbol
3244 name definitions differing only in case (these are reported as duplicates).
3245
3246-Wimmediate
3247 Warns for cases where immediate addressing is more likely.
3248
3249 It may be hard to notice if a `#' was missed. The code still compiles but
3250 there's a huge difference between `cpx #const' and `cpx const'. Unless the
3251 right sort of garbage was on zero page at the time of testing...
3252
3253 This check might have a lot of false positives if zero page locations are
3254 accessed by using small numbers, which is a popular coding style. But there
3255 are ways to reduce them.
3256
3257 For "known" fixed locations address(x) can be used, preferably bound to a
3258 symbol. Automatic allocation of zero page variables works too (e.g. zpstuff
3259 .byte ?). And basically everything which is a traditional "label" or
3260 derived from a label with an offset.
3261
3262-Wimplied-reg
3263 Warns if implied addressing is used instead of register.
3264
3265 Some instructions have implied aliases like `asl' for `asl a' for
3266 compatibility reasons, but this shorthand is not the preferred form.
3267
3268-Wleading-zeros
3269 Warns if about leading zeros.
3270
3271 A leading zero could be a prefix for an octal number but as octals are not
3272 supported the result will be decimal.
3273
3274-Wlong-branch
3275 Warns when a long branch is used.
3276
3277 This option gives a warning for instructions which were modified by the
3278 long branch function. Less intrusive than disabling long branches and see
3279 where it fails.
3280
3281-Wmacro-prefix
3282 Warn about macro call without prefix.
3283
3284 Such macro calls can easily be mistaken to be labels if invoked without
3285 parameters. Also it's hard to notice that an unchanged call turned into
3286 label after the definition got renamed. This warning helps to find such
3287 calls so that prefixes can be added.
3288
3289-Wno-deprecated
3290 Don't warn about deprecated features.
3291
3292 Unfortunately there were some features added previously which shouldn't
3293 have been included. This option disables warnings about their uses.
3294
3295-Wno-float-compare
3296 Don't warn if floating point comparisons are only approximate.
3297
3298 Floating point numbers have a finite precision and comparing them might
3299 give unexpected results.
3300
3301 For example 2.1 + 0.2 == 2.3 is true but gives a warning as the left side
3302 is actually bigger by approximately 4.44E-16.
3303
3304 Normally this is solved by rounding or changing the comparison values.
3305
3306-Wfloat-round
3307 Warn when floating point numbers are implicitly rounded.
3308
3309 A lot of parameters and the data dumping directives need integers but
3310 floating point numbers are accepted as well. The style of rounding used may
3311 or may not be what you wanted.
3312
3313 By default floor rounding (to lower) is used and not truncate (towards
3314 zero). The reason for this is to enable calculation of fixed point integers
3315 by using floating point.
3316
3317 The difference is subtle and only noticable for negative numbers. The
3318 division of -300/256 is -2 which matches floor(-300/256.0) but not trunc
3319 (-300/256.0).
3320
3321 To get symmetric sine waves around zero trunc() needs to be used. Some
3322 other calculation might result in 126.9999997 due to inaccuracies in
3323 logarithm which would need round().
3324
3325 To avoid unexpected rounding this option helps to find those places where
3326 no explicit rounding was done.
3327
3328-Wno-ignored
3329 Don't warn about ignored directives.
3330-Wno-jmp-bug
3331 Don't warn about the jmp ($xxff) bug.
3332
3333 With this option it's fine that the high byte is read from the `wrong'
3334 address on a 6502, NMOS 6502 and 65DTV02.
3335
3336-Wno-label-left
3337 Don't warn about certain labels not being on left side.
3338
3339 You may disable this if you use labels which look like mistyped versions of
3340 implied addressing mode instructions and you don't want to put them in the
3341 first column.
3342
3343 This check is there to catch typos, unsupported implied instructions, or
3344 unknown aliases and not for enforcing label placement.
3345
3346-Wno-page
3347 Don't do an error for page crossing
3348
3349 Normally the .page directive gives an error on page crossing, this
3350 directive can disable it. Using `-Wno-error=page' can turn it into a
3351 warning only.
3352
3353-Wno-pitfalls
3354 Don't note about common pitfalls.
3355
3356 There are some common mistakes, but experts and those who read this don't
3357 need extra notes about them. These are:
3358
3359 Use multi character strings with `.byte' instead of `.text'.
3360 This fails because `.byte' enforces the 0-255 range for each value.
3361 Using `label *=*+1' style space reservations.
3362 Warns as `*=' is also the compound multiply operator. The `*=*+1' needs
3363 to be on a separate line without a label. A better alternatively is to
3364 use `.fill 1' or `.byte ?'.
3365 Negative numbers with `.byte' or `.word'
3366 There are other directives which accept them with proper range checks
3367 like `.char', `.sint'.
3368 Negative numbers with `lda #xxx'
3369 There's a signed variant for the immediate addressing so `lda #+xx'
3370 will make it work
3371
3372-Wno-portable
3373 Don't warn about source portability problems.
3374
3375 These cross platform development annoyances are checked for:
3376
3377 + Case insensitive use of file names or use of short names.
3378 + Use of backslashes for path separation instead of forward slashes.
3379 + Use of reserved characters in file names.
3380 + Absolute paths
3381-Wno-size-larger
3382 Don't warn if size is larger due to negative offset
3383
3384 size() and len() can be used to measure a memory area. Normally there's no
3385 offset used but a positive offset may be used to reduce available space up
3386 until nothing remains.
3387
3388 On the other hand if a negative offset is used then more space will be
3389 available (ahead of the area) which may or may not be desired.
3390
3391 var .byte ?, ?, ?
3392 var2 = var - 2 ; start 2 bytes earlier
3393 ldx #size(var2) ; size is 6 bytes due to 2 bytes ahead
3394
3395-Wno-star-assign
3396 Don't warn about ignored compound multiply.
3397
3398 Normally `symbol *= ...' means compound multiply of the variable in front.
3399 Unfortunately this looks the same a `label *=*+x' which is an old-school
3400 way to allocate space.
3401
3402 If the symbol was a variable defined earlier then the multiply is performed
3403 without a warning. If it's a new label definition then this warning is used
3404 to note that maybe a variable definition was missed earlier.
3405
3406 If the intention was really a label definition then the `*=' can be moved
3407 to a separate line, or in case of space allocation it could be improved to
3408 use `.byte ?' or `.fill x'.
3409
3410-Wno-wrap-addr
3411 Don't warn about memory location address space wrap around.
3412
3413 Applying offsets to memory locations may result in addresses which end up
3414 outside of the processors address space.
3415
3416 For example "tmp" is at $1000 and then it's addressed as lda tmp-$2000 then
3417 the result will be lda $f000 or lda $fff000 depending on the CPU. If this
3418 is fine then this warning can be disabled otherwise it can be made into an
3419 error by using -Werror=wrap-addr.
3420
3421-Wno-wrap-bank0
3422 Don't warn for bank 0 wrap around.
3423
3424 Adding an offset to a bank 0 address may end up outside of bank 0. If this
3425 happens a warning is issued and the address wraps around.
3426
3427 The warning may be ignored using this command line parameter. Alternatively
3428 it could be turned into an error by using -Werror=wrap-bank0.
3429
3430-Wno-wrap-dpage
3431 Don't warn for direct page wrap around.
3432
3433 Adding an offset to a direct page address may end up outside of the direct
3434 page. For a 65816 or 65EL02 an alternative addressing mode is used but on
3435 other processors if this happens a warning is issued and the address wraps
3436 around.
3437
3438 The warning may be ignored using this command line parameter. Alternatively
3439 it could be turned into an error by using -Werror=wrap-dpage.
3440
3441-Wno-wrap-mem
3442 Don't warn for compile offset wrap around.
3443
3444 While assembling the compile offset may reach the end of memory image. If
3445 this happens a warning is issued and the compile offset is set to the start
3446 of image.
3447
3448 The warning may be ignored using this command line parameter. Alternatively
3449 it could be turned into an error by using -Werror=wrap-mem.
3450
3451 The image size depends on the output format. See the Output options section
3452 above.
3453
3454-Wno-wrap-pc
3455 Don't warn for program counter bank crossing.
3456
3457 While assembling the program counter may reach the end of the current
3458 program bank. If this happens a warning is issued as a real CPU will not
3459 cross the bank on execution. On the other hand some addressing modes handle
3460 bank crosses so this might not be actually a problem for data.
3461
3462 The warning may be ignored using this command line parameter. Alternatively
3463 it could be turned into an error by using -Werror=wrap-pc.
3464
3465-Wno-wrap-pbank
3466 Don't warn for program bank address calculation wrap around.
3467
3468 Adding an offset to a program bank address may end up outside of the
3469 current program bank. If this happens a warning is issued and the address
3470 wraps around.
3471
3472 The warning may be ignored using this command line parameter. Alternatively
3473 it could be turned into an error by using -Werror=wrap-pbank.
3474
3475-Wold-equal
3476 Warn about old equal operator.
3477
3478 The single `=' operator is only there for compatibility reasons and should
3479 be written as `==' normally.
3480
3481-Woptimize
3482 Warn about optimizable code.
3483
3484 Warns on things that could be optimized, at least according to the limited
3485 analysis done. Currently it's easy to fool with these constructs:
3486
3487 + Self modifying code, especially modifying immediate addressing mode
3488 instructions or branch targets
3489 + Using .byte $2c and similar tricks to skip instructions.
3490 + Using *+5 and similar tricks to skip instructions, or to loop like *-1.
3491 + Any other method of flow control not involving referenced labels. E.g.
3492 calculated returns.
3493 + Register re-mappings on 65DTV02 with SIR and SAC.
3494
3495 It's also rather simple and conservative, so some opportunities will be
3496 missed. Most CPUs are supported with the notable exception of 65816 and
3497 65EL02, but this could improve in later versions.
3498
3499-Wshadow
3500 Warn about symbol shadowing.
3501
3502 Checks if local variables `shadow' other variables of same name in upper
3503 scopes in ambiguous ways.
3504
3505 This is useful to detect hard to notice bugs where a new local variable
3506 takes the place of a global one by mistake.
3507
3508 bl .block
3509 a .byte 2 ;'a' is a built-in register
3510 x .byte 2 ;'x' is a built-in register
3511 asl a ; accumulator or the byte above?
3512 .end
3513 asl bl.x ; not ambiguous
3514
3515-Wstrict-bool
3516 Warn about implicit boolean conversions.
3517
3518 Boolean values can be interpreted as numeric 0/1 and other types as
3519 booleans. This is convenient but may cause mistakes.
3520
3521 To pass this option the following constructs need improvements:
3522
3523 + `1' and `0' as boolean constants. Use the slightly longer `true' and
3524 `false'.
3525 + Implicit non-zero checks. Write it out like `.if (lbl & 1) != 0'.
3526 + Zero checks with `!'. Write it out like `lbl == 0'.
3527 + Binary operators on booleans. Use the proper `||', `&&' and `^^'
3528 operators.
3529 + Numeric expressions like `1 + (lbl > 3)'. It's better as `(lbl > 3) ? 2
3530 : 1'.
3531-Wunused
3532 Warn about unused constant symbols.
3533
3534 Symbols which have no references to them are likely redundant. Before
3535 removing them check if there's any conditionally compiled out code which
3536 might still need them.
3537
3538 The following options can be used to be more specific:
3539
3540 -Wunused-const
3541 Warn about unused constants.
3542 -Wunused-label
3543 Warn about unused labels.
3544 -Wunused-macro
3545 Warn about unused macros.
3546 -Wunused-variable
3547 Warn about unused variables.
3548
3549 Symbols which appear in a default 64tass symbol list file and their root
3550 symbols are treated as used for exporting purposes.
3551
3552Target selection on command line
3553
3554These options will select the default architecture. It can be overridden by
3555using the .cpu directive in the source.
3556
3557--m65xx
3558 Standard 65xx (default). For writing compatible code, no extra codes. This
3559 is the default.
3560
3561 64tass --m65xx a.asm
3562 lda $14 ;regular instructions
3563
3564-c, --m65c02
3565 CMOS 65C02. Enables extra opcodes and addressing modes specific to this
3566 CPU.
3567
3568 64tass --m65c02 a.asm
3569 stz $d020 ;65c02 instruction
3570
3571--m65ce02
3572 CSG 65CE02. Enables extra opcodes and addressing modes specific to this
3573 CPU.
3574
3575 64tass --m65ce02 a.asm
3576 inz
3577
3578-i, --m6502
3579 NMOS 65xx. Enables extra illegal opcodes. Useful for demo coding for C64,
3580 disk drive code, etc.
3581
3582 64tass --m6502 a.asm
3583 lax $14 ;illegal instruction
3584
3585-t, --m65dtv02
3586 65DTV02. Enables extra opcodes specific to DTV.
3587
3588 64tass --m65dtv02 a.asm
3589 sac #$00
3590
3591-x, --m65816
3592 W65C816. Enables extra opcodes. Useful for SuperCPU projects.
3593
3594 64tass --m65816 a.asm
3595 lda $123456,x
3596
3597-e, --m65el02
3598 65EL02. Enables extra opcodes, useful RedPower CPU projects. Probably
3599 you'll need `--nostart' as well.
3600
3601 64tass --m65el02 a.asm
3602 lda #0,r
3603
3604--mr65c02
3605 R65C02. Enables extra opcodes and addressing modes specific to this CPU.
3606
3607 64tass --mr65c02 a.asm
3608 rmb 7,$20
3609
3610--mw65c02
3611 W65C02. Enables extra opcodes and addressing modes specific to this CPU.
3612
3613 64tass --mw65c02 a.asm
3614 wai
3615
3616--m4510
3617 CSG 4510. Enables extra opcodes and addressing modes specific to this CPU.
3618 Useful for C65 projects.
3619
3620 64tass --m4510 a.asm
3621 map
3622 eom
3623
3624Symbol listing
3625
3626-l <file>, --labels=<file>
3627 List symbols into <file>.
3628
3629 64tass -l labels.txt a.asm
3630 * = $1000
3631 label jmp label
3632
3633 result (labels.txt):
3634 label = $1000
3635
3636 This option may be used multiple times. In this case the format and root
3637 scope options must be placed before this option. Using the same name
3638 multiple times is not a good idea.
3639
3640 64tass --vice-labels -l all.l --export-labels --labels-root=export -l myexport.inc source.asm
3641
3642 This writes symbols for VICE into `all.l' and symbols from scope `export'
3643 into `myexport.inc'.
3644
3645--labels-append=<file>
3646 Same as the --labels option but appends instead of overwrites.
3647--labels-root=<path>
3648 Specify the scope to list labels from
3649
3650 This option can be used to limit the output to only a subset of labels. The
3651 parameter is a dot separated path to a scope started from the global scope.
3652
3653--normal-labels
3654 Lists labels in a 64tass readable format. (default)
3655
3656 List labels without any side effects. Usually for display purposes or for
3657 later include.
3658
3659--export-labels
3660 List labels for include in a 64tass readable format.
3661
3662 The difference to normal symbol listing is that 64tass assumes these
3663 symbols will be used in another source. In practice this means that any
3664 .proc/.endproc blocks appearing in the symbol file will always be compiled
3665 even if unused otherwise.
3666
3667--vice-labels
3668 List labels in a VICE readable format.
3669
3670 This format may be used to translate memory locations to something readable
3671 in VICE monitor. Therefore simple numeric constants will not show up unless
3672 converted to an address first.
3673
3674 VICE symbols may only contain ASCII letters, numbers and underscore.
3675 Symbols not meeting this requirement will be omitted.
3676
3677 There's a good chance VICE will complain about already existing labels on
3678 import. In the past an attempt was made to filter out such duplicates to
3679 eliminate these warnings. However soon it was pointed out that omitted
3680 labels are now unavailable for commands like setting breakpoints. As the
3681 latter use case is rather more important than some bogus import warnings
3682 one has to live with them.
3683
3684 64tass --vice-labels -l labels.l a.asm
3685 * = $1000
3686 label jmp label
3687
3688 result (labels.l):
3689 al 1000 .label
3690
3691 For now colons are used as scope delimiter due to a VICE limitation, but
3692 this will be changed to dots in the future.
3693
3694--vice-labels-numeric
3695 List address like symbols in a VICE readable format including numeric
3696 constants.
3697
3698 The normal VICE label list does not include symbols like chrout = $ffd2 or
3699 keybuff = 631 as these are numeric constants and not memory addresses.
3700
3701 Of course there are ways around that. For example:
3702
3703 chrout = address($ffd2)
3704 keybuff = address(631)
3705 * = $ffd2
3706 chrout .fill 3
3707 * = 631
3708 keybuff .fill 10
3709
3710 For those who don't want to waste time on explicitly marking addresses as
3711 such there's an easy way out by using this command line option.
3712
3713 The tradeoff is that depending on the coding style the label list will
3714 become polluted by non-address constants to various degrees. However if one
3715 mostly uses numeric constants for addresses only this may be acceptable.
3716
3717--dump-labels
3718 List labels for debugging.
3719
3720 The output will contain symbol locations and paths.
3721
3722Assembly listing
3723
3724-L <file>, --list=<file>
3725 List into <file>. Dumps source code and compiled code into file. Useful for
3726 debugging, it's much easier to identify the code in memory within the
3727 source files.
3728
3729 ; 64tass Turbo Assembler Macro V1.5x listing file
3730 ; 64tass -L list.txt a.asm
3731 ; Fri Dec 9 19:08:55 2005
3732
3733 ;Offset ;Hex ;Monitor ;Source
3734
3735 ;****** Processing input file: a.asm
3736
3737 .1000 a2 00 ldx #$00 ldx #0
3738 .1002 ca dex loop dex
3739 .1003 d0 fd bne $1002 bne loop
3740 .1005 60 rts rts
3741
3742 ;****** End of listing
3743
3744-m, --no-monitor
3745 Don't put monitor code into listing. There won't be any monitor listing in
3746 the list file.
3747
3748 ; 64tass Turbo Assembler Macro V1.5x listing file
3749 ; 64tass --no-monitor -L list.txt a.asm
3750 ; Fri Dec 9 19:11:43 2005
3751
3752 ;Offset ;Hex ;Source
3753
3754 ;****** Processing input file: a.asm
3755
3756 .1000 a2 00 ldx #0
3757 .1002 ca loop dex
3758 .1003 d0 fd bne loop
3759 .1005 60 rts
3760
3761 ;****** End of listing
3762
3763-s, --no-source
3764 Don't put source code into listing. There won't be any source listing in
3765 the list file.
3766
3767 ; 64tass Turbo Assembler Macro V1.5x listing file
3768 ; 64tass --no-source -L list.txt a.asm
3769 ; Fri Dec 9 19:13:25 2005
3770
3771 ;Offset ;Hex ;Monitor
3772
3773 ;****** Processing input file: a.asm
3774
3775 .1000 a2 00 ldx #$00
3776 .1002 ca dex
3777 .1003 d0 fd bne $1002
3778 .1005 60 rts
3779
3780 ;****** End of listing
3781
3782--line-numbers
3783 This option creates a new column for showing line numbers for easier
3784 identification of source origin. The line number is followed with an
3785 optional colon separated file number in case it comes from a different file
3786 then the previous lines.
3787
3788 ; 64tass Turbo Assembler Macro V1.5x listing file
3789 ; 64tass --line-numbers -L list.txt a.asm
3790 ; Fri Dec 9 19:13:25 2005
3791
3792 ;Line ;Offset ;Hex ;Monitor ;Source
3793
3794 :1 ;****** Processing input file: a.asm
3795
3796 3 .1000 a2 00 ldx #$00 ldx #0
3797 4 .1002 ca dex loop dex
3798 5 .1003 d0 fd bne $1002 bne loop
3799 6 .1005 60 rts rts
3800
3801 ;****** End of listing
3802
3803--tab-size=<number>
3804 By default the listing file is using a tab size of 8 to align the
3805 disassembly. This can be changed to other more favorable values like 4.
3806 Only spaces are used if 1 is selected. Please note that this has no effect
3807 on the source code on the right hand side.
3808--verbose-list
3809 Normally the assembler tries to minimize listing output by omitting
3810 "unimportant" lines. But sometimes it's better to just list everything
3811 including comments and empty lines.
3812
3813 ; 64tass Turbo Assembler Macro V1.5x listing file
3814 ; 64tass --verbose-list -L list.txt a.asm
3815 ; Fri Dec 9 19:13:25 2005
3816
3817 ;Offset ;Hex ;Monitor ;Source
3818
3819 ;****** Processing input file: a.asm
3820
3821 * = $1000
3822
3823 .1000 a2 00 ldx #$00 ldx #0
3824 .1002 ca dex loop dex
3825 .1003 d0 fd bne $1002 bne loop
3826 .1005 60 rts rts
3827
3828 ;****** End of listing
3829
3830Other options
3831
3832-?, --help
3833 Give this help list. Prints help about command line options.
3834--usage
3835 Give a short usage message. Prints short help about command line options.
3836-V, --version
3837 Print program version
3838
3839Command line from file
3840
3841Command line arguments can be read from a file as well. This is useful to store
3842common options for multiple files in one place or to overcome the argument list
3843length limitations of some systems.
3844
3845The filename needs to be prefixed with an at sign, so `@argsfile' reads options
3846from `argsfile'. It will only work if there's not another file named
3847`@argsfile'. The content is expanded in-place of `@argsfile'.
3848
3849Stored options must be separated by white space. Single or double quotes can be
3850used in case file names have white space in their names.
3851
3852Backslash can be used to escape the character following it and it must be used
3853to escape itself. Single and double quotes need to be escaped if needed for
3854string quoting.
3855
3856Forward slashes can be used as a portable path separation on all systems.
3857
3858-------------------------------------------------------------------------------
3859
3860Messages
3861
3862Faults and warnings encountered are sent to the standard error for logging. To
3863redirect them to a file append `2>filename.log' after the command or use the `
3864-E' command line option. The message format is the following:
3865
3866<filename>:<line>:<character>: <severity>: <message>
3867
3868 * filename: The name and path of source file where the error happened.
3869 * line: Line number in file, starts from 1.
3870 * character: Character in line, starts from 1. Tabs are not expanded.
3871 * severity: Note, warning, error or fatal.
3872 * message: The fault message itself.
3873
3874The faulty line will be displayed after the message with a caret pointing to
3875the error location unless this is disabled by using `--no-caret-diag' option.
3876
3877a.asm:3:21: error: not defined symbol 'label'
3878 lda label
3879 ^
3880a.asm:3:21: note: searched in the global scope
3881
3882This is helpful for macro expansions as it displays the processed line which
3883usually looks different to the one in the original source file.
3884
3885Error buried deep in included files or macros display a backtrace of files
3886after an `In file included from' text where all the files and positions
3887involved are listed down to the main file.
3888
3889In file included from main.asm:3:3:
3890included.asm:2:11: error: not defined symbol 'test'
3891 #macro1 test
3892 ^
3893In file included from included.asm:2:3,
3894 main.asm:3:3:
3895macros.asm:3:7: note: original location in an expanded macro was here
3896 lda test
3897 ^
3898
3899Messages ending with `[-Wxxx]' are user controllable. This means that using
3900`-Wno-xxx' on the command line will silence them and `-Werror=xxx' will turn
3901them it into a fault. See Diagnostic options for more details.
3902
3903Warnings
3904
3905approximate floating point
3906 floating point comparisons are not exact and the numbers were close but
3907 maybe not quite
3908bank 0 address overflow
3909 the calculated memory location address ended up outside of bank 0 and is
3910 now wrapped.
3911case ignored, value already handled
3912 this value was already used in an earlier case so here it's ignored
3913compile offset overflow
3914 compile continues at the bottom ($0000) as end of compile area was reached
3915constant result, possibly changeable to 'lda'
3916 a pre-calculated value could be loaded instead as the result seems to be
3917 always the same
3918could be shorter by using 'xxx' instead
3919 this shorter instruction gives the same result according to the optimizer
3920could be simpler by using 'xxx' instead
3921 this instruction gives the same result but with less dependencies according
3922 to the optimizer
3923deprecated directive, only for TASM compatible mode
3924 .goto and .lbl should only be used in TASM compatible mode and there are
3925 better ways to loop
3926deprecated equal operator, use '==' instead
3927 single equal sign for comparisons is going away soon, update source
3928deprecated modulo operator, use '%' instead
3929 double slash for modulo is going away soon, update source
3930deprecated not equal operator, use '!=' instead
3931 non-standard not equal operators which will stop working in the future,
3932 update source
3933direct page address overflow
3934 the calculated memory location address ended up outside of direct page and
3935 is now wrapped.
3936directive ignored
3937 an assembler directive was ignored for compatibility reasons
3938expected ? values but got ? to unpack
3939 the number of variables must match the number of values when unpacking
3940file name uses reserved character '?'
3941 do not use \ : * ? " < > | in file names as some operating systems don't
3942 like these
3943immediate addressing mode suggested
3944 numeric constant was used as an address which was likely meant as an
3945 immediate value
3946implicit floating point rounding
3947 a floating point number with fractional part was used for an integer
3948 parameter
3949independent result, possibly changeable to 'lda'
3950 the result does not seem to depend on the input so it could be just loaded
3951 instead
3952instruction 'xxx' is an alias of 'xxx'
3953 an alternative instruction name was used
3954label defined instead of variable multiplication for compatibility
3955 move the '*=' construct to a separate line or define the variable first as
3956 this construct is ambiguous
3957label not on left side
3958 check if an instruction name was not mistyped and if the current CPU has
3959 it, or remove white space before label
3960leading zeros ignored
3961 leading zeros in front of decimals are redundant and don't denote an octal
3962 number
3963long branch used
3964 branch distance was too long so long branch was used (bxx *+5 jmp)
3965memory location address overflow
3966 the calculated memory location address ended up outside of the processors
3967 address space
3968please use format("%d", ...) as '^' will change it's meaning
3969 this operator will be changed to mean the bank byte later, please update
3970 your sources
3971please use quotes now to allow expressions in future
3972 the directive will allow expressions later and the parameter will be a
3973 string
3974possible jmp ($xxff) bug
3975 some 6502 variants read don't increment the high byte on page cross and
3976 this may be unexpected
3977possibly redundant as ...
3978 according to the optimizer this might not be needed
3979possibly redundant if last 'jsr' is changed to 'jmp'
3980 tail call elimination possibility was detected
3981possibly redundant indexing with a constant value
3982 the index register used seems to be constant and there's a way to eliminate
3983 indexing by a constant offset
3984processor program counter crossed bank
3985 pc address had crossed into another 64 KiB program bank
3986program bank address overflow
3987 the calculated memory location address ended up outside of the current
3988 program bank and is now wrapped.
3989symbol case mismatch '?'
3990 the symbol is matching case insensitively but it's not all letters are
3991 exactly the same
3992the file's real name is not '?'
3993 check if all characters match including their case as this is not the real
3994 name of the file
3995unused symbol '?'
3996 this symbol has is not referred anywhere and therefore may be unused
3997use '/' as path separation '?'
3998 backslash is not a path separator on all systems while forward slash will
3999 work independent of the host operating system
4000use relative path for '?'
4001 file's path is absolute and depends on the file system layout and the
4002 source will not compile without the exact same environment
4003
4004Errors
4005
4006'?' expected
4007 something is missing
4008? argument is missing
4009 not enough arguments supplied
4010address in different program bank
4011 this instruction is only limited to access the current bank
4012address not in processor address space
4013 value larger than current CPU address space
4014address out of section
4015 moving the address around is fine as long as it does not end up before the
4016 start of the section
4017addressing mode too complex
4018 too much indexing or indirection for a valid address
4019at least one byte is needed
4020 the expression didn't yield any bytes but it's needed here
4021branch crosses page by ? bytes
4022 page crossing was on branch was detected
4023branch too far by ? bytes
4024 branches have limited range and this went over by some bytes
4025can't calculate stable value
4026 somehow it's impossible to calculate this expression
4027can't calculate this
4028 could not get any value, is this a circular reference?
4029can't encode character '?' ($xx) in encoding '?'
4030 can't translate character in this encoding as no definition was given
4031can't get absolute value of
4032 not possible to calculate the absolute value of this type
4033can't get boolean value of
4034 not possible to determine if this value is true or false
4035can't get integer value of
4036 this value is not a number
4037can't get length of
4038 this type has no length
4039can't get sign of
4040 this type does not have a sign as it's not a number
4041can't get size of
4042 this type has no size
4043closing/opening directive '?' not found
4044 couldn't find the other half of block directive pair
4045conflict
4046 at least one feature is provided, which shouldn't be there
4047conversion of ? '?' to ? is not possible
4048 this type conversion can't be done
4049division by zero
4050 dividing with zero can't be done
4051double defined escape
4052 escape sequence already defined in another .edef differently
4053double defined range
4054 part of a character range was already defined by another .cdef and these
4055 ranges can't overlap
4056duplicate definition
4057 symbol defined more than once
4058empty encoding, add something or correct name
4059 probably a typo in the name of encoding but if not then use .cdef/.edef to
4060 define something
4061empty list not allowed
4062 at least one element is required
4063empty range not allowed
4064 invalid range but there must be at least one element
4065empty string not allowed
4066 at least one character is required
4067expected exactly/at least/at most ? arguments, got ?
4068 wrong number of function arguments used
4069expression syntax
4070 syntax error
4071extra characters on line
4072 there's some garbage on the end of line
4073floating point overflow
4074 infinity reached during a calculation
4075format character expected
4076 string ended before a format character was found
4077general syntax
4078 can't do anything with this
4079index out of range
4080 not enough elements in list
4081key not in dictionary
4082 key not in the dictionary
4083label required
4084 a label is mandatory for this directive
4085larger than original due to negative offset
4086 if a negative offset is used the size gets larger than the original as this
4087 effectively adds bytes to the front.
4088last byte must not be gap
4089 .shift or .shiftl needs a normal byte at the end
4090logarithm of non-positive number
4091 only positive numbers have a logarithm
4092macro call without prefix
4093 macro call was found without a prefix and without parameters
4094more than a single character
4095 no more than a single character is allowed
4096more than two characters
4097 no more than two characters are allowed
4098most significant bit must be clear in byte
4099 for .shift and .shiftl only 7 bit "bytes" are valid
4100must be used within a loop
4101 .break or .continue must be used within a loop
4102negative number raised on fractional power
4103 can't calculate this
4104no ? addressing mode for opcode 'xxx'
4105 this addressing mode is not valid for this instruction
4106not a bank 0 address
4107 value must be a bank zero address
4108not a data bank address
4109 value must be a data bank address
4110not a direct page address
4111 value must be a direct page address
4112not a key and value pair
4113 dictionaries are built from key and value pairs separated by a colon
4114not a variable
4115 only variables are changeable
4116not defined '?'
4117 can't find this label at this point
4118not hashable
4119 the type can't be used as a key in a dictionary
4120not in range -1.0 to 1.0
4121 the function is only valid in the -1.0 to 1.0 range
4122not iterable
4123 value is not a list or other iterable object
4124not measurable as start offset beyond size of original
4125 the applied offset was larger than the original size. For example if size
4126 (data) is 2 then size(data + 1) is 1. However size(data + 3) makes no sense
4127 as there's no such thing as a negative size.
4128offset out of range
4129 code offset too much
4130operands could not be broadcast together with shapes ? and ?
4131 list length must match or must have a single element only
4132different start and end page $xxxx and $xxxx
4133 page crossing was detected
4134ptext too long by ? bytes
4135 .ptext is limited to 255 bytes maximum
4136requirements not met
4137 not all features are provided, at least one is missing
4138reserved symbol name '?'
4139 do not use this symbol name
4140shadow definition
4141 symbol is defined in an upper scope as well and is used ambiguously
4142some operation '?' of type '?' and type '?' not possible
4143 can't do this calculation with these values
4144square root of negative number
4145 can't calculate the square root of a negative number
4146too large for a ? bit signed/unsigned integer
4147 value out of range
4148unknown processor '?'
4149 unknown cpu name
4150unknown argument name '?'
4151 no parameter argument known like this
4152unknown format character '?'
4153 no format character known like this
4154value needs to be non-negative
4155 only positive numbers or zero is accepted here
4156wrong type <?>
4157 wrong object type used
4158zero raised to negative power
4159 can't calculate this
4160zero value not allowed
4161 do not use zero for example with .null
4162
4163Fatal errors
4164
4165can't open file
4166 cannot open file
4167can't write error file
4168 cannot write the error file
4169can't write label file
4170 cannot write the label file
4171can't write listing file
4172 cannot write the list file
4173can't write make file
4174 cannot write the make rule file
4175can't write object file
4176 cannot write the result
4177compilation was interrupted
4178 shows the line where the interruption happened
4179error reading file
4180 error while reading
4181file recursion
4182 wrong nesting of .include
4183function recursion too deep
4184 wrong use of nested functions
4185macro recursion too deep
4186 wrong use of nested macros
4187option '?' doesn't allow an argument
4188 command line option doesn't need any argument
4189option '?' is ambiguous
4190 command line option abbreviation is too short
4191option '?' not recognized
4192 no such command line option
4193option '?' requires an argument
4194 command line option needs an argument
4195out of memory
4196 won't happen ;)
4197scope '?' for label listing not found
4198 the scope given on command line couldn't be found
4199section '?' for output not found
4200 the section given on command line couldn't be found
4201too many passes
4202 with a carefully crafted source file it's possible to create unresolvable
4203 situations but try to avoid this
4204unknown option '?'
4205 option not known
4206weak recursion
4207 excessive nesting of .weak
4208
4209-------------------------------------------------------------------------------
4210
4211Credits
4212
4213Original 6502tass written for DOS by Marek Matula of Taboo.
4214
4215It was ported to ANSI C by BigFoot/Breeze. This is when it's name changed to
421664tass.
4217
4218Soci/Singular reworked the code over the years to the point that practically
4219nothing was left from original at this point.
4220
4221Improved TASS compatibility, PETSCII codes by Groepaz.
4222
4223Additional code: my_getopt command-line argument parser by Benjamin Sittler,
4224avl tree code by Franck Bui-Huu, ternary tree code by Daniel Berlin, snprintf
4225Alain Magloire, Amiga OS4 support files by Janne Per?aho.
4226
4227Pierre Zero helped to uncover a lot of faults by fuzzing. Also there were a lot
4228of discussions with oziphantom about the need of various features.
4229
4230Main developer and maintainer: soci at c64.rulez.org
4231
4232-------------------------------------------------------------------------------
4233
4234Default translation and escape sequences
4235
4236Raw 8-bit source
4237
4238By default raw 8-bit encoding is used and nothing is translated or escaped.
4239This mode is for compiling sources which are already PETSCII.
4240
4241The `none' encoding for raw 8-bit
4242
4243Does no translation at all, no translation table, no escape sequences.
4244
4245The `screen' encoding for raw 8-bit
4246
4247The following translation table applies, no escape sequences.
4248
4249 Built-in PETSCII to PETSCII screen code translation table
4250 Input Byte Input Byte
425100-1F 80-9F 20-3F 20-3F
425240-5F 00-1F 60-7F 40-5F
425380-9F 80-9F A0-BF 60-7F
4254C0-FE 40-7E FF 5E
4255
4256Unicode and ASCII source
4257
4258Unicode encoding is used when the `-a' option is given on the command line.
4259
4260The `none' encoding for Unicode
4261
4262This is a Unicode to PETSCII mapping, including escape sequences for control
4263codes.
4264
4265 Built-in Unicode to PETSCII translation table
4266 Glyph Unicode Byte Glyph Unicode Byte
4267 -@ U+0020-U+0040 20-40 A-Z U+0041-U+005A C1-DA
4268[ U+005B 5B ] U+005D 5D
4269a-z U+0061-U+007A 41-5A ? U+00A3 5C
4270? U+03C0 FF ? U+2190 5F
4271? U+2191 5E ? U+2500 C0
4272? U+2502 DD ? U+250C B0
4273? U+2510 AE ? U+2514 AD
4274? U+2518 BD ? U+251C AB
4275? U+2524 B3 ? U+252C B2
4276? U+2534 B1 ? U+253C DB
4277? U+256D D5 ? U+256E C9
4278? U+256F CB ? U+2570 CA
4279? U+2571 CE ? U+2572 CD
4280? U+2573 D6 ? U+2581 A4
4281? U+2582 AF ? U+2583 B9
4282? U+2584 A2 ? U+258C A1
4283? U+258D B5 ? U+258E B4
4284? U+258F A5 ? U+2592 A6
4285? U+2594 A3 ? U+2595 A7
4286? U+2596 BB ? U+2597 AC
4287? U+2598 BE ? U+259A BF
4288? U+259D BC ? U+25CB D7
4289? U+25CF D1 ? U+25E4 A9
4290? U+25E5 DF ? U+2660 C1
4291? U+2663 D8 ? U+2665 D3
4292? U+2666 DA ? U+2713 BA
4293? U+1FB70 D4 ? U+1FB71 C7
4294? U+1FB72 C2 ? U+1FB73 DD
4295? U+1FB74 C8 ? U+1FB75 D9
4296? U+1FB76 C5 ? U+1FB77 C4
4297? U+1FB78 C3 ? U+1FB79 C0
4298? U+1FB7A C6 ? U+1FB7B D2
4299? U+1FB7C CC ? U+1FB7D CF
4300? U+1FB7E D0 ? U+1FB7F BA
4301? U+1FB82 B7 ? U+1FB83 B8
4302? U+1FB87 AA ? U+1FB88 B6
4303? U+1FB8C DC ? U+1FB8F A8
4304? U+1FB95 FF ? U+1FB98 DF
4305? U+1FB99 A9
4306
4307 Built-in PETSCII escape sequences
4308 Escape Byte Escape Byte Escape Byte
4309{bell} 07 {black} 90 {blk} 90
4310{blue} 1F {blu} 1F {brn} 95
4311{brown} 95 {cbm-*} DF {cbm-+} A6
4312{cbm--} DC {cbm-0} 30 {cbm-1} 81
4313{cbm-2} 95 {cbm-3} 96 {cbm-4} 97
4314{cbm-5} 98 {cbm-6} 99 {cbm-7} 9A
4315{cbm-8} 9B {cbm-9} 29 {cbm-@} A4
4316{cbm-^} DE {cbm-a} B0 {cbm-b} BF
4317{cbm-c} BC {cbm-d} AC {cbm-e} B1
4318{cbm-f} BB {cbm-g} A5 {cbm-h} B4
4319{cbm-i} A2 {cbm-j} B5 {cbm-k} A1
4320{cbm-l} B6 {cbm-m} A7 {cbm-n} AA
4321{cbm-o} B9 {cbm-pound} A8 {cbm-p} AF
4322{cbm-q} AB {cbm-r} B2 {cbm-s} AE
4323{cbm-t} A3 {cbm-up arrow} DE {cbm-u} B8
4324{cbm-v} BE {cbm-w} B3 {cbm-x} BD
4325{cbm-y} B7 {cbm-z} AD {clear} 93
4326{clr} 93 {control-0} 92 {control-1} 90
4327{control-2} 05 {control-3} 1C {control-4} 9F
4328{control-5} 9C {control-6} 1E {control-7} 1F
4329{control-8} 9E {control-9} 12 {control-:} 1B
4330{control-;} 1D {control-=} 1F {control-@} 00
4331{control-a} 01 {control-b} 02 {control-c} 03
4332{control-d} 04 {control-e} 05 {control-f} 06
4333{control-g} 07 {control-h} 08 {control-i} 09
4334{control-j} 0A {control-k} 0B {control-left arrow} 06
4335{control-l} 0C {control-m} 0D {control-n} 0E
4336{control-o} 0F {control-pound} 1C {control-p} 10
4337{control-q} 11 {control-r} 12 {control-s} 13
4338{control-t} 14 {control-up arrow} 1E {control-u} 15
4339{control-v} 16 {control-w} 17 {control-x} 18
4340{control-y} 19 {control-z} 1A {cr} 0D
4341{cyan} 9F {cyn} 9F {delete} 14
4342{del} 14 {dish} 08 {down} 11
4343{ensh} 09 {esc} 1B {f10} 82
4344{f11} 84 {f12} 8F {f1} 85
4345{f2} 89 {f3} 86 {f4} 8A
4346{f5} 87 {f6} 8B {f7} 88
4347{f8} 8C {f9} 80 {gray1} 97
4348{gray2} 98 {gray3} 9B {green} 1E
4349{grey1} 97 {grey2} 98 {grey3} 9B
4350{grn} 1E {gry1} 97 {gry2} 98
4351{gry3} 9B {help} 84 {home} 13
4352{insert} 94 {inst} 94 {lblu} 9A
4353{left arrow} 5F {left} 9D {lf} 0A
4354{lgrn} 99 {lower case} 0E {lred} 96
4355{lt blue} 9A {lt green} 99 {lt red} 96
4356{orange} 81 {orng} 81 {pi} FF
4357{pound} 5C {purple} 9C {pur} 9C
4358{red} 1C {return} 0D {reverse off} 92
4359{reverse on} 12 {rght} 1D {right} 1D
4360{run} 83 {rvof} 92 {rvon} 12
4361{rvs off} 92 {rvs on} 12 {shift return} 8D
4362{shift-*} C0 {shift-+} DB {shift-,} 3C
4363{shift--} DD {shift-.} 3E {shift-/} 3F
4364{shift-0} 30 {shift-1} 21 {shift-2} 22
4365{shift-3} 23 {shift-4} 24 {shift-5} 25
4366{shift-6} 26 {shift-7} 27 {shift-8} 28
4367{shift-9} 29 {shift-:} 5B {shift-;} 5D
4368{shift-@} BA {shift-^} DE {shift-a} C1
4369{shift-b} C2 {shift-c} C3 {shift-d} C4
4370{shift-e} C5 {shift-f} C6 {shift-g} C7
4371{shift-h} C8 {shift-i} C9 {shift-j} CA
4372{shift-k} CB {shift-l} CC {shift-m} CD
4373{shift-n} CE {shift-o} CF {shift-pound} A9
4374{shift-p} D0 {shift-q} D1 {shift-r} D2
4375{shift-space} A0 {shift-s} D3 {shift-t} D4
4376{shift-up arrow} DE {shift-u} D5 {shift-v} D6
4377{shift-w} D7 {shift-x} D8 {shift-y} D9
4378{shift-z} DA {space} 20 {sret} 8D
4379{stop} 03 {swlc} 0E {swuc} 8E
4380{tab} 09 {up arrow} 5E {up/lo lock off} 09
4381{up/lo lock on} 08 {upper case} 8E {up} 91
4382{white} 05 {wht} 05 {yellow} 9E
4383{yel} 9E
4384
4385The `screen' encoding for Unicode
4386
4387This is a Unicode to PETSCII screen code mapping, including escape sequences
4388for control code screen codes.
4389
4390 Built-in Unicode to PETSCII screen code translation table
4391 Glyph Unicode Translated Glyph Unicode Translated
4392 -? U+0020-U+003F 20-3F @ U+0040 00
4393A-Z U+0041-U+005A 41-5A [ U+005B 1B
4394] U+005D 1D a-z U+0061-U+007A 01-1A
4395? U+00A3 1C ? U+03C0 5E
4396? U+2190 1F ? U+2191 1E
4397? U+2500 40 ? U+2502 5D
4398? U+250C 70 ? U+2510 6E
4399? U+2514 6D ? U+2518 7D
4400? U+251C 6B ? U+2524 73
4401? U+252C 72 ? U+2534 71
4402? U+253C 5B ? U+256D 55
4403? U+256E 49 ? U+256F 4B
4404? U+2570 4A ? U+2571 4E
4405? U+2572 4D ? U+2573 56
4406? U+2581 64 ? U+2582 6F
4407? U+2583 79 ? U+2584 62
4408? U+258C 61 ? U+258D 75
4409? U+258E 74 ? U+258F 65
4410? U+2592 66 ? U+2594 63
4411? U+2595 67 ? U+2596 7B
4412? U+2597 6C ? U+2598 7E
4413? U+259A 7F ? U+259D 7C
4414? U+25CB 57 ? U+25CF 51
4415? U+25E4 69 ? U+25E5 5F
4416? U+2660 41 ? U+2663 58
4417? U+2665 53 ? U+2666 5A
4418? U+2713 7A ? U+1FB70 54
4419? U+1FB71 47 ? U+1FB72 42
4420? U+1FB73 5D ? U+1FB74 48
4421? U+1FB75 59 ? U+1FB76 45
4422? U+1FB77 44 ? U+1FB78 43
4423? U+1FB79 40 ? U+1FB7A 46
4424? U+1FB7B 52 ? U+1FB7C 4C
4425? U+1FB7D 4F ? U+1FB7E 50
4426? U+1FB7F 7A ? U+1FB82 77
4427? U+1FB83 78 ? U+1FB87 6A
4428? U+1FB88 76 ? U+1FB8C 5C
4429? U+1FB8F 68 ? U+1FB95 5E
4430? U+1FB98 5F ? U+1FB99 69
4431
4432 Built-in PETSCII screen code escape sequences
4433 Escape Byte Escape Byte Escape Byte
4434{cbm-*} 5F {cbm-+} 66 {cbm--} 5C
4435{cbm-0} 30 {cbm-9} 29 {cbm-@} 64
4436{cbm-^} 5E {cbm-a} 70 {cbm-b} 7F
4437{cbm-c} 7C {cbm-d} 6C {cbm-e} 71
4438{cbm-f} 7B {cbm-g} 65 {cbm-h} 74
4439{cbm-i} 62 {cbm-j} 75 {cbm-k} 61
4440{cbm-l} 76 {cbm-m} 67 {cbm-n} 6A
4441{cbm-o} 79 {cbm-pound} 68 {cbm-p} 6F
4442{cbm-q} 6B {cbm-r} 72 {cbm-s} 6E
4443{cbm-t} 63 {cbm-up arrow} 5E {cbm-u} 78
4444{cbm-v} 7E {cbm-w} 73 {cbm-x} 7D
4445{cbm-y} 77 {cbm-z} 6D {left arrow} 1F
4446{pi} 5E {pound} 1C {shift-*} 40
4447{shift-+} 5B {shift-,} 3C {shift--} 5D
4448{shift-.} 3E {shift-/} 3F {shift-0} 30
4449{shift-1} 21 {shift-2} 22 {shift-3} 23
4450{shift-4} 24 {shift-5} 25 {shift-6} 26
4451{shift-7} 27 {shift-8} 28 {shift-9} 29
4452{shift-:} 1B {shift-;} 1D {shift-@} 7A
4453{shift-^} 5E {shift-a} 41 {shift-b} 42
4454{shift-c} 43 {shift-d} 44 {shift-e} 45
4455{shift-f} 46 {shift-g} 47 {shift-h} 48
4456{shift-i} 49 {shift-j} 4A {shift-k} 4B
4457{shift-l} 4C {shift-m} 4D {shift-n} 4E
4458{shift-o} 4F {shift-pound} 69 {shift-p} 50
4459{shift-q} 51 {shift-r} 52 {shift-space} 60
4460{shift-s} 53 {shift-t} 54 {shift-up arrow} 5E
4461{shift-u} 55 {shift-v} 56 {shift-w} 57
4462{shift-x} 58 {shift-y} 59 {shift-z} 5A
4463{space} 20 {up arrow} 1E
4464
4465-------------------------------------------------------------------------------
4466
4467Opcodes
4468
4469Standard 6502 opcodes
4470
4471 The standard 6502 opcodes
4472ADC 61 65 69 6D 71 75 79 7D AND 21 25 29 2D 31 35 39 3D
4473ASL 06 0A 0E 16 1E BCC 90
4474BCS B0 BEQ F0
4475BIT 24 2C BMI 30
4476BNE D0 BPL 10
4477BRK 00 BVC 50
4478BVS 70 CLC 18
4479CLD D8 CLI 58
4480CLV B8 CMP C1 C5 C9 CD D1 D5 D9 DD
4481CPX E0 E4 EC CPY C0 C4 CC
4482DEC C6 CE D6 DE DEX CA
4483DEY 88 EOR 41 45 49 4D 51 55 59 5D
4484INC E6 EE F6 FE INX E8
4485INY C8 JMP 4C 6C
4486JSR 20 LDA A1 A5 A9 AD B1 B5 B9 BD
4487LDX A2 A6 AE B6 BE LDY A0 A4 AC B4 BC
4488LSR 46 4A 4E 56 5E NOP EA
4489ORA 01 05 09 0D 11 15 19 1D PHA 48
4490PHP 08 PLA 68
4491PLP 28 ROL 26 2A 2E 36 3E
4492ROR 66 6A 6E 76 7E RTI 40
4493RTS 60 SBC E1 E5 E9 ED F1 F5 F9 FD
4494SEC 38 SED F8
4495SEI 78 STA 81 85 8D 91 95 99 9D
4496STX 86 8E 96 STY 84 8C 94
4497TAX AA TAY A8
4498TSX BA TXA 8A
4499TXS 9A TYA 98
4500
4501 Aliases, pseudo instructions
4502ASL 0A BGE B0
4503BLT 90 CPA C1 C5 C9 CD D1 D5 D9 DD
4504GCC 4C 90 GCS 4C B0
4505GEQ 4C F0 GGE 4C B0
4506GLT 4C 90 GMI 30 4C
4507GNE 4C D0 GPL 10 4C
4508GVC 4C 50 GVS 4C 70
4509LSR 4A ROL 2A
4510ROR 6A SHL 06 0A 0E 16 1E
4511SHR 46 4A 4E 56 5E
4512
4513-------------------------------------------------------------------------------
4514
45156502 illegal opcodes
4516
4517This processor is a standard 6502 with the NMOS illegal opcodes.
4518
4519 Additional opcodes
4520ANC 0B ANE 8B
4521ARR 6B ASR 4B
4522DCP C3 C7 CF D3 D7 DB DF ISB E3 E7 EF F3 F7 FB FF
4523JAM 02 LAX A3 A7 AB AF B3 B7 BF
4524LDS BB NOP 04 0C 14 1C 80
4525RLA 23 27 2F 33 37 3B 3F RRA 63 67 6F 73 77 7B 7F
4526SAX 83 87 8F 97 SBX CB
4527SHA 93 9F SHS 9B
4528SHX 9E SHY 9C
4529SLO 03 07 0F 13 17 1B 1F SRE 43 47 4F 53 57 5B 5F
4530
4531 Additional aliases
4532AHX 93 9F ALR 4B
4533AXS CB DCM C3 C7 CF D3 D7 DB DF
4534INS E3 E7 EF F3 F7 FB FF ISC E3 E7 EF F3 F7 FB FF
4535LAE BB LAS BB
4536LXA AB TAS 9B
4537XAA 8B
4538
4539-------------------------------------------------------------------------------
4540
454165DTV02 opcodes
4542
4543This processor is an enhanced version of standard 6502 with some illegal
4544opcodes.
4545
4546 Additionally to 6502 illegal opcodes
4547BRA 12 SAC 32
4548SIR 42
4549
4550 Additional pseudo instruction
4551GRA 12 4C
4552
4553 These illegal opcodes are not valid
4554ANC 0B JAM 02
4555LDS BB NOP 04 0C 14 1C 80
4556SBX CB SHA 93 9F
4557SHS 9B SHX 9E
4558SHY 9C
4559
4560 These aliases are not valid
4561AHX 93 9F AXS CB
4562LAE BB LAS BB
4563TAS 9B
4564
4565-------------------------------------------------------------------------------
4566
4567Standard 65C02 opcodes
4568
4569This processor is an enhanced version of standard 6502.
4570
4571 Additional opcodes
4572ADC 72 AND 32
4573BIT 34 3C 89 BRA 80
4574CMP D2 DEC 3A
4575EOR 52 INC 1A
4576JMP 7C LDA B2
4577ORA 12 PHX DA
4578PHY 5A PLX FA
4579PLY 7A SBC F2
4580STA 92 STZ 64 74 9C 9E
4581TRB 14 1C TSB 04 0C
4582
4583 Additional aliases and pseudo instructions
4584CLR 64 74 9C 9E CPA D2
4585DEA 3A GRA 4C 80
4586INA 1A
4587
4588-------------------------------------------------------------------------------
4589
4590R65C02 opcodes
4591
4592This processor is an enhanced version of standard 65C02.
4593
4594Please note that the bit number is not part of the instruction name (like rmb7
4595$20). Instead it's the first element of coma separated parameters (e.g. rmb
45967,$20).
4597
4598 Additional opcodes
4599BBR 0F 1F 2F 3F 4F 5F 6F 7F BBS 8F 9F AF BF CF DF EF FF
4600NOP 44 54 82 DC RMB 07 17 27 37 47 57 67 77
4601SMB 87 97 A7 B7 C7 D7 E7 F7
4602
4603-------------------------------------------------------------------------------
4604
4605W65C02 opcodes
4606
4607This processor is an enhanced version of R65C02.
4608
4609 Additional opcodes
4610STP DB WAI CB
4611
4612 Additional aliases
4613HLT DB
4614
4615-------------------------------------------------------------------------------
4616
4617W65816 opcodes
4618
4619This processor is an enhanced version of 65C02.
4620
4621 Additional opcodes
4622ADC 63 67 6F 73 77 7F AND 23 27 2F 33 37 3F
4623BRL 82 CMP C3 C7 CF D3 D7 DF
4624COP 02 EOR 43 47 4F 53 57 5F
4625JMP 5C DC JSL 22
4626JSR FC LDA A3 A7 AF B3 B7 BF
4627MVN 54 MVP 44
4628ORA 03 07 0F 13 17 1F PEA F4
4629PEI D4 PER 62
4630PHB 8B PHD 0B
4631PHK 4B PLB AB
4632PLD 2B REP C2
4633RTL 6B SBC E3 E7 EF F3 F7 FF
4634SEP E2 STA 83 87 8F 93 97 9F
4635STP DB TCD 5B
4636TCS 1B TDC 7B
4637TSC 3B TXY 9B
4638TYX BB WAI CB
4639WDM 42 XBA EB
4640XCE FB
4641
4642 Additional aliases
4643CLP C2 CPA C3 C7 CF D3 D7 DF
4644CSP 02 HLT DB
4645JML 5C DC SWA EB
4646TAD 5B TAS 1B
4647TDA 7B TSA 3B
4648
4649-------------------------------------------------------------------------------
4650
465165EL02 opcodes
4652
4653This processor is an enhanced version of standard 65C02.
4654
4655 Additional opcodes
4656ADC 63 67 73 77 AND 23 27 33 37
4657CMP C3 C7 D3 D7 DIV 4F 5F 6F 7F
4658ENT 22 EOR 43 47 53 57
4659JSR FC LDA A3 A7 B3 B7
4660MMU EF MUL 0F 1F 2F 3F
4661NXA 42 NXT 02
4662ORA 03 07 13 17 PEA F4
4663PEI D4 PER 62
4664PHD DF PLD CF
4665REA 44 REI 54
4666REP C2 RER 82
4667RHA 4B RHI 0B
4668RHX 1B RHY 5B
4669RLA 6B RLI 2B
4670RLX 3B RLY 7B
4671SBC E3 E7 F3 F7 SEA 9F
4672SEP E2 STA 83 87 93 97
4673STP DB SWA EB
4674TAD BF TDA AF
4675TIX DC TRX AB
4676TXI 5C TXR 8B
4677TXY 9B TYX BB
4678WAI CB XBA EB
4679XCE FB ZEA 8F
4680
4681 Additional aliases
4682CLP C2 CPA C3 C7 D3 D7
4683HLT DB
4684
4685-------------------------------------------------------------------------------
4686
468765CE02 opcodes
4688
4689This processor is an enhanced version of R65C02.
4690
4691 Additional opcodes
4692ASR 43 44 54 ASW CB
4693BCC 93 BCS B3
4694BEQ F3 BMI 33
4695BNE D3 BPL 13
4696BRA 83 BSR 63
4697BVC 53 BVS 73
4698CLE 02 CPZ C2 D4 DC
4699DEW C3 DEZ 3B
4700INW E3 INZ 1B
4701JSR 22 23 LDA E2
4702LDZ A3 AB BB NEG 42
4703PHW F4 FC PHZ DB
4704PLZ FB ROW EB
4705RTS 62 SEE 03
4706STA 82 STX 9B
4707STY 8B TAB 5B
4708TAZ 4B TBA 7B
4709TSY 0B TYS 2B
4710TZA 6B
4711
4712 Additional aliases
4713ASR 43 BGE B3
4714BLT 93 NEG 42
4715RTN 62
4716
4717 This alias is not valid
4718CLR 64 74 9C 9E
4719
4720-------------------------------------------------------------------------------
4721
4722CSG 4510 opcodes
4723
4724This processor is an enhanced version of 65CE02.
4725
4726 Additional opcodes
4727MAP 5C
4728
4729 Additional aliases
4730EOM EA
4731
4732-------------------------------------------------------------------------------
4733
4734Appendix
4735
4736Assembler directives
4737
4738.addr .al .align .as .assert .autsiz .bend .binary .binclude .bfor .block
4739.break .breakif .brept .bwhile .byte .case .cdef .cerror .char .check .comment
4740.continue .continueif .cpu .cwarn .databank .default .dint .dpage .dsection
4741.dstruct .dunion .dword .edef .else .elsif .enc .end .endblock .endc
4742.endcomment .endf .endfor .endfunction .endif .endlogical .endm .endmacro .endn
4743.endnamespace .endp .endpage .endproc .endrept .ends .endsection .endsegment
4744.endstruct .endswitch .endu .endunion .endv .endvirtual .endweak .endwhile
4745.endwith .eor .error .fi .fill .for .function .goto .here .hidemac .if .ifeq
4746.ifmi .ifne .ifpl .include .lbl .lint .logical .long .macro .mansiz .namespace
4747.next .null .offs .option .page .pend .proc .proff .pron .ptext .rept .rta
4748.section .seed .segment .send .sfunction .shift .shiftl .showmac .sint .struct
4749.switch .text .union .var .virtual .warn .weak .while .with .word .xl .xs
4750
4751-------------------------------------------------------------------------------
4752
4753Built-in functions
4754
4755abs acos addr all any asin atan atan2 binary byte cbrt ceil char cos cosh deg
4756dint dword exp floor format frac hypot len lint log log10 long pow rad random
4757range repr round rta sign sin sinh sint size sort sqrt tan tanh trunc word
4758
4759Built-in types
4760
4761address bits bool bytes code dict float gap int list str tuple type
4762
4763