X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fca65.sgml;h=21103999517f8be68fd7805c442150cfcfd858bf;hb=74455508314bc2b007e812ec5f9429496b9fbd5f;hp=278a81d1bef9ca1ce780203e7e7d12ba11e7e065;hpb=67cd0c219726b8d6ef5fc5e980cc197fbfb257d7;p=cc65 diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 278a81d1b..211039995 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -2,8 +2,8 @@
ca65 Users Guide -<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz"> -<date>2015-08-01 +<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline> +<url url="mailto:greg.king5@verizon.net" name="Greg King"> <abstract> ca65 is a powerful macro assembler for the 6502, 65C02, and 65816 CPUs. It is @@ -36,42 +36,42 @@ development: <itemize> -<item> The assembler must support macros. Macros are not essential, but they - make some things easier, especially when you use the assembler in the - backend of a compiler. -<item> The assembler must support the newer 65C02 and 65816 CPUs. I have been - thinking about a 65816 backend for the C compiler, and even my old - a816 assembler had support for these CPUs, so this wasn't really a - problem. -<item> The assembler must produce relocatable code. This is necessary for the - compiler support, and it is more convenient. -<item> Conditional assembly must be supported. This is a must for bigger - projects written in assembler (like Elite128). -<item> The assembler must support segments, and it must support more than - three segments (this is the count, most other assemblers support). - Having more than one code segments helps developing code for systems - with a divided ROM area (like the C64). -<item> The linker must be able to resolve arbitrary expressions. It should - be able to get things like +<item> The assembler must support macros. Macros are not essential, but they + make some things easier, especially when you use the assembler in the + backend of a compiler. +<item> The assembler must support the newer 65C02 and 65816 CPUs. I have been + thinking about a 65816 backend for the C compiler, and even my old + a816 assembler had support for these CPUs, so this wasn't really a + problem. +<item> The assembler must produce relocatable code. This is necessary for the + compiler support, and it is more convenient. +<item> Conditional assembly must be supported. This is a must for bigger + projects written in assembler (like Elite128). +<item> The assembler must support segments, and it must support more than + three segments (this is the count, most other assemblers support). + Having more than one code segments helps developing code for systems + with a divided ROM area (like the C64). +<item> The linker must be able to resolve arbitrary expressions. It should + be able to get things like <tscreen><verb> - .import S1, S2 - .export Special - Special = 2*S1 + S2/7 + .import S1, S2 + .export Special + Special = 2*S1 + S2/7 </verb></tscreen> - right. -<item> True lexical nesting for symbols. This is very convenient for larger - assembly projects. -<item> "Cheap" local symbols without lexical nesting for those quick, late - night hacks. -<item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I - introduced the concept into the object file format use by the new cc65 - binutils. -<item> The assembler will be a one pass assembler. There was no real need for - this decision, but I've written several multipass assemblers, and it - started to get boring. A one pass assembler needs much more elaborated - data structures, and because of that it's much more fun:-) -<item> Non-GPLed code that may be used in any project without restrictions or - fear of "GPL infecting" other code. + right. +<item> True lexical nesting for symbols. This is very convenient for larger + assembly projects. +<item> "Cheap" local symbols without lexical nesting for those quick, late + night hacks. +<item> I liked the idea of "options" as Anre Fachats .o65 format has it, so I + introduced the concept into the object file format use by the new cc65 + binutils. +<item> The assembler will be a one pass assembler. There was no real need for + this decision, but I've written several multipass assemblers, and it + started to get boring. A one pass assembler needs much more elaborated + data structures, and because of that it's much more fun:-) +<item> Non-GPLed code that may be used in any project without restrictions or + fear of "GPL infecting" other code. </itemize> <p> @@ -151,7 +151,7 @@ Here is a description of all the command line options: Set the default for the CPU type. The option takes a parameter, which may be one of - 6502, 65SC02, 65C02, 65816, sweet16, HuC6280 + 6502, 6502X, 65SC02, 65C02, 65816, sweet16, HuC6280, 4510 <label id="option-create-dep"> @@ -403,13 +403,13 @@ it is ignored). Here are some examples for valid input lines: <tscreen><verb> - Label: ; A label and a comment - lda #$20 ; A 6502 instruction plus comment - L1: ldx #$20 ; Same with label - L2: .byte "Hello world" ; Label plus control command - mymac $20 ; Macro expansion - MySym = 3*L1 ; Symbol definition - MaSym = Label ; Another symbol + Label: ; A label and a comment + lda #$20 ; A 6502 instruction plus comment + L1: ldx #$20 ; Same with label + L2: .byte "Hello world" ; Label plus control command + mymac $20 ; Macro expansion + MySym = 3*L1 ; Symbol definition + MaSym = Label ; Another symbol </verb></tscreen> The assembler accepts @@ -423,8 +423,10 @@ The assembler accepts <tt><ref id=".PSC02" name=".PSC02"></tt> command was given). <item>all valid 65C02 mnemonics when in 65C02 mode (after the <tt><ref id=".PC02" name=".PC02"></tt> command was given). -<item>all valid 65618 mnemonics when in 65816 mode (after the +<item>all valid 65816 mnemonics when in 65816 mode (after the <tt><ref id=".P816" name=".P816"></tt> command was given). +<item>all valid 4510 mnemonics when in 4510 mode (after the + <tt><ref id=".P4510" name=".P4510"></tt> command was given). </itemize> @@ -433,16 +435,16 @@ The assembler accepts In 65816 mode, several aliases are accepted, in addition to the official mnemonics: -<tscreen><verb> -CPA is an alias for CMP -DEA is an alias for DEC A -INA is an alias for INC A -SWA is an alias for XBA -TAD is an alias for TCD -TAS is an alias for TCS -TDA is an alias for TDC -TSA is an alias for TSC -</verb></tscreen> +<itemize> +<item><tt>CPA</tt> is an alias for <tt>CMP</tt> +<item><tt>DEA</tt> is an alias for <tt>DEC A</tt> +<item><tt>INA</tt> is an alias for <tt>INC A</tt> +<item><tt>SWA</tt> is an alias for <tt>XBA</tt> +<item><tt>TAD</tt> is an alias for <tt>TCD</tt> +<item><tt>TAS</tt> is an alias for <tt>TCS</tt> +<item><tt>TDA</tt> is an alias for <tt>TDC</tt> +<item><tt>TSA</tt> is an alias for <tt>TSC</tt> +</itemize> <sect1>6502X mode<label id="6502X-mode"><p> @@ -472,6 +474,27 @@ from the mentioned web page, for more information, see there. </itemize> +<sect1>4510 mode<p> + +The 4510 is a microcontroller that is the core of the Commodore C65 aka C64DX. +It contains among other functions a slightly modified 65CE02/4502 CPU, to allow +address mapping for 20 bits of address space (1 megabyte addressable area). +As compared to the description of the CPU in the +<url url="http://www.zimmers.net/anonftp/pub/cbm/c65/c65manualupdated.txt.gz" +name="C65 System Specification"> +<url url="https://raw.githubusercontent.com/MEGA65/c65-specifications/master/c65manualupdated.txt" +name="(updated version)"> uses these changes: +<itemize> +<item><tt>LDA (d,SP),Y</tt> may also be written as <tt>LDA (d,S),Y</tt> +(matching the 65816 notataion). +<item>All branch instruction allow now 16 bit offsets. To use a 16 bit +branch you have to prefix these with an "L" (e.g. "<tt>LBNE</tt>" instead of +"<tt>BNE</tt>"). This might change at a later implementation of the assembler. +</itemize> +For more information about the Commodore C65/C64DX and the 4510 CPU, see +<url url="http://www.zimmers.net/anonftp/pub/cbm/c65/"> and +<url url="https://en.wikipedia.org/wiki/Commodore_65" name="Wikipedia">. + <sect1>sweet16 mode<label id="sweet16-mode"><p> @@ -542,19 +565,19 @@ case, the assembler has to make some assumptions about the result of an expression: <itemize> -<item> If the result of an expression is constant, the actual value is - checked to see if it's a byte sized expression or not. -<item> If the expression is explicitly casted to a byte sized expression by - one of the '>', '<' or '^' operators, it is a byte expression. -<item> If this is not the case, and the expression contains a symbol, - explicitly declared as zero page symbol (by one of the .importzp or - .exportzp instructions), then the whole expression is assumed to be - byte sized. -<item> If the expression contains symbols that are not defined, and these - symbols are local symbols, the enclosing scopes are searched for a - symbol with the same name. If one exists and this symbol is defined, - its attributes are used to determine the result size. -<item> In all other cases the expression is assumed to be word sized. +<item> If the result of an expression is constant, the actual value is + checked to see if it's a byte sized expression or not. +<item> If the expression is explicitly casted to a byte sized expression by + one of the '>', '<' or '^' operators, it is a byte expression. +<item> If this is not the case, and the expression contains a symbol, + explicitly declared as zero page symbol (by one of the .importzp or + .exportzp instructions), then the whole expression is assumed to be + byte sized. +<item> If the expression contains symbols that are not defined, and these + symbols are local symbols, the enclosing scopes are searched for a + symbol with the same name. If one exists and this symbol is defined, + its attributes are used to determine the result size. +<item> In all other cases the expression is assumed to be word sized. </itemize> Note: If the assembler is not able to evaluate the expression at assembly @@ -763,14 +786,14 @@ You may use cheap local labels as an easy way to reuse common label names like "Loop". Here is an example: <tscreen><verb> - Clear: lda #$00 ; Global label - ldy #$20 - @Loop: sta Mem,y ; Local label - dey - bne @Loop ; Ok - rts - Sub: ... ; New global label - bne @Loop ; ERROR: Unknown identifier! + Clear: lda #$00 ; Global label + ldy #$20 + @Loop: sta Mem,y ; Local label + dey + bne @Loop ; Ok + rts + Sub: ... ; New global label + bne @Loop ; ERROR: Unknown identifier! </verb></tscreen> <sect1>Unnamed labels<p> @@ -786,23 +809,23 @@ reference (use the n'th label in forward direction). An example will help to understand this: <tscreen><verb> - : lda (ptr1),y ; #1 - cmp (ptr2),y - bne :+ ; -> #2 - tax - beq :+++ ; -> #4 - iny - bne :- ; -> #1 - inc ptr1+1 - inc ptr2+1 - bne :- ; -> #1 - - : bcs :+ ; #2 -> #3 - ldx #$FF - rts - - : ldx #$01 ; #3 - : rts ; #4 + : lda (ptr1),y ; #1 + cmp (ptr2),y + bne :+ ; -> #2 + tax + beq :+++ ; -> #4 + iny + bne :- ; -> #1 + inc ptr1+1 + inc ptr2+1 + bne :- ; -> #1 + + : bcs :+ ; #2 -> #3 + ldx #$FF + rts + + : ldx #$01 ; #3 + : rts ; #4 </verb></tscreen> As you can see from the example, unnamed labels will make even short @@ -834,15 +857,15 @@ errors. Because of these problems, the general advice is, <bf/NOT/ do use Example: <tscreen><verb> - .DEFINE two 2 - .DEFINE version "SOS V2.3" + .DEFINE two 2 + .DEFINE version "SOS V2.3" - four = two * two ; Ok - .byte version ; Ok + four = two * two ; Ok + .byte version ; Ok - .PROC ; Start local scope - two = 3 ; Will give "2 = 3" - invalid! - .ENDPROC + .PROC ; Start local scope + two = 3 ; Will give "2 = 3" - invalid! + .ENDPROC </verb></tscreen> @@ -1163,7 +1186,21 @@ an explanation on how this is done. <sect1>Address sizes of symbols<p> +The address size of a symbol can be specified with a prefix: +<itemize> +<item>z: zeropage addressing (8 bits). +<item>a: absolute addressing (16 bits). +<item>f: far addressing (24 bits). +</itemize> + +The zeropage addressing override can be used to ensure the use of optimal +zeropage instructions, or correct cases where the size isn't yet known +due to the single-pass assembly model. + +The larger addressing overrides can be used to promote a smaller address +to absolute or far addressing, instead of being automatically fit into +a smaller addressing type. <sect1>Memory models<p> @@ -1204,17 +1241,17 @@ writable. Example: <tscreen><verb> - ; Reverse Subtract with Accumulator - ; A = memory - A - .macro rsb param - .if .asize = 8 - eor #$ff - .else - eor #$ffff - .endif - sec - adc param - .endmacro + ; Reverse Subtract with Accumulator + ; A = memory - A + .macro rsb param + .if .asize = 8 + eor #$ff + .else + eor #$ffff + .endif + sec + adc param + .endmacro </verb></tscreen> See also: <tt><ref id=".ISIZE" name=".ISIZE"></tt> @@ -1235,15 +1272,15 @@ writable. <tscreen><verb> .macpack cpu - .if (.cpu .bitand CPU_ISET_65816) - phx - phy - .else - txa - pha - tya - pha - .endif + .if (.cpu .bitand CPU_ISET_65816) + phx + phy + .else + txa + pha + tya + pha + .endif </verb></tscreen> @@ -1268,12 +1305,12 @@ writable. Example: <tscreen><verb> - .macro foo arg1, arg2, arg3 - .if .paramcount <> 3 - .error "Too few parameters for macro foo" - .endif - ... - .endmacro + .macro foo arg1, arg2, arg3 + .if .paramcount <> 3 + .error "Too few parameters for macro foo" + .endif + ... + .endmacro </verb></tscreen> See section <ref id="macros" name="Macros">. @@ -1320,8 +1357,8 @@ either a string or an expression. <sect1><tt>.ADDRSIZE</tt><label id=".ADDRSIZE"><p> - The <tt/.ADDRSIZE/ function is used to return the interal address size - associated with a symbol. This can be helpful in macros when knowing the address + The <tt/.ADDRSIZE/ function is used to return the interal address size + associated with a symbol. This can be helpful in macros when knowing the address size of symbol can help with custom instructions. Example: @@ -1380,7 +1417,7 @@ either a string or an expression. .endproc .proc bank_table - .addr banked_func_1 + .addr banked_func_1 .byte <.BANK (banked_func_1) .addr banked_func_2 @@ -1412,7 +1449,7 @@ either a string or an expression. As an example, the <tt/.IFBLANK/ statement may be replaced by <tscreen><verb> - .if .blank({arg}) + .if .blank({arg}) </verb></tscreen> @@ -1428,13 +1465,13 @@ either a string or an expression. Example: <tscreen><verb> - .include .concat ("myheader", ".", "inc") + .include .concat ("myheader", ".", "inc") </verb></tscreen> This is the same as the command <tscreen><verb> - .include "myheader.inc" + .include "myheader.inc" </verb></tscreen> @@ -1446,7 +1483,7 @@ either a string or an expression. otherwise. As an example, the .IFCONST statement may be replaced by <tscreen><verb> - .if .const(a + 3) + .if .const(a + 3) </verb></tscreen> @@ -1476,7 +1513,7 @@ either a string or an expression. Example: <tscreen><verb> - .macro makelabel arg1, arg2 + .macro makelabel arg1, arg2 .ident (.concat (arg1, arg2)): .endmacro @@ -1493,7 +1530,7 @@ either a string or an expression. Syntax: <tscreen><verb> - .LEFT (<int expr>, <token list>) + .LEFT (<int expr>, <token list>) </verb></tscreen> The first integer expression gives the number of tokens to extract from @@ -1508,16 +1545,16 @@ either a string or an expression. (immediate addressing mode), use something like this: <tscreen><verb> - .macro ldax arg - ... - .if (.match (.left (1, {arg}), #)) + .macro ldax arg + ... + .if (.match (.left (1, {arg}), #)) - ; ldax called with immediate operand - ... + ; ldax called with immediate operand + ... - .endif - ... - .endmacro + .endif + ... + .endmacro </verb></tscreen> See also the <tt><ref id=".MID" name=".MID"></tt> and <tt><ref id=".RIGHT" @@ -1549,7 +1586,7 @@ either a string or an expression. The syntax is <tscreen><verb> - .MATCH(<token list #1>, <token list #2>) + .MATCH(<token list #1>, <token list #2>) </verb></tscreen> Both token list may contain arbitrary tokens with the exception of the @@ -1580,16 +1617,16 @@ either a string or an expression. to check for this and print and error for invalid calls. <tscreen><verb> - .macro asr arg + .macro asr arg - .if (.not .blank(arg)) .and (.not .match ({arg}, a)) - .error "Syntax error" - .endif + .if (.not .blank(arg)) .and (.not .match ({arg}, a)) + .error "Syntax error" + .endif - cmp #$80 ; Bit 7 into carry - lsr a ; Shift carry into bit 7 + cmp #$80 ; Bit 7 into carry + lsr a ; Shift carry into bit 7 - .endmacro + .endmacro </verb></tscreen> The macro will only accept no arguments, or one argument that must be the @@ -1605,14 +1642,14 @@ either a string or an expression. The syntax is <tscreen><verb> - .MAX (<value #1>, <value #2>) + .MAX (<value #1>, <value #2>) </verb></tscreen> Example: <tscreen><verb> ; Reserve space for the larger of two data blocks - savearea: .max (.sizeof (foo), .sizeof (bar)) + savearea: .res .max (.sizeof (foo), .sizeof (bar)) </verb></tscreen> See: <tt><ref id=".MIN" name=".MIN"></tt> @@ -1626,7 +1663,7 @@ either a string or an expression. Syntax: <tscreen><verb> - .MID (<int expr>, <int expr>, <token list>) + .MID (<int expr>, <int expr>, <token list>) </verb></tscreen> The first integer expression gives the starting token in the list (the first @@ -1642,16 +1679,16 @@ either a string or an expression. (immediate addressing mode), use something like this: <tscreen><verb> - .macro ldax arg - ... - .if (.match (.mid (0, 1, {arg}), #)) + .macro ldax arg + ... + .if (.match (.mid (0, 1, {arg}), #)) - ; ldax called with immediate operand - ... + ; ldax called with immediate operand + ... - .endif - ... - .endmacro + .endif + ... + .endmacro </verb></tscreen> See also the <tt><ref id=".LEFT" name=".LEFT"></tt> and <tt><ref id=".RIGHT" @@ -1665,14 +1702,14 @@ either a string or an expression. The syntax is <tscreen><verb> - .MIN (<value #1>, <value #2>) + .MIN (<value #1>, <value #2>) </verb></tscreen> Example: <tscreen><verb> - ; Reserve space for some data, but 256 bytes minimum - savearea: .min (.sizeof (foo), 256) + ; Reserve space for some data, but 256 bytes maximum + savearea: .res .min (.sizeof (foo), 256) </verb></tscreen> See: <tt><ref id=".MAX" name=".MAX"></tt> @@ -1687,7 +1724,7 @@ either a string or an expression. the <tt><ref id=".IFREF" name=".IFREF"></tt> statement may be replaced by <tscreen><verb> - .if .referenced(a) + .if .referenced(a) </verb></tscreen> See: <tt><ref id=".DEFINED" name=".DEFINED"></tt> @@ -1700,7 +1737,7 @@ either a string or an expression. Syntax: <tscreen><verb> - .RIGHT (<int expr>, <token list>) + .RIGHT (<int expr>, <token list>) </verb></tscreen> The first integer expression gives the number of tokens to extract from the @@ -1796,12 +1833,12 @@ either a string or an expression. Example: <tscreen><verb> - .macro M Arg - ; Check if the argument string starts with '#' - .if (.strat (Arg, 0) = '#') - ... - .endif - .endmacro + .macro M Arg + ; Check if the argument string starts with '#' + .if (.strat (Arg, 0) = '#') + ... + .endif + .endmacro </verb></tscreen> @@ -1836,10 +1873,10 @@ either a string or an expression. Example: <tscreen><verb> - ; Emulate other assemblers: - .macro section name - .segment .string(name) - .endmacro + ; Emulate other assemblers: + .macro section name + .segment .string(name) + .endmacro </verb></tscreen> @@ -1854,9 +1891,9 @@ either a string or an expression. a leading length byte. <tscreen><verb> - .macro PString Arg - .byte .strlen(Arg), Arg - .endmacro + .macro PString Arg + .byte .strlen(Arg), Arg + .endmacro </verb></tscreen> @@ -1876,15 +1913,15 @@ either a string or an expression. load instructions, the '#' token has to get stripped from the argument: <tscreen><verb> - .macro ldax arg - .if (.match (.mid (0, 1, {arg}), #)) - ; ldax called with immediate operand - lda #<(.right (.tcount ({arg})-1, {arg})) - ldx #>(.right (.tcount ({arg})-1, {arg})) - .else - ... - .endif - .endmacro + .macro ldax arg + .if (.match (.mid (0, 1, {arg}), #)) + ; ldax called with immediate operand + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) + .else + ... + .endif + .endmacro </verb></tscreen> @@ -1897,7 +1934,7 @@ either a string or an expression. The syntax is <tscreen><verb> - .XMATCH(<token list #1>, <token list #2>) + .XMATCH(<token list #1>, <token list #2>) </verb></tscreen> Both token list may contain arbitrary tokens with the exception of the @@ -1957,7 +1994,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .addr $0D00, $AF13, _Clear + .addr $0D00, $AF13, _Clear </verb></tscreen> See: <tt><ref id=".FARADDR" name=".FARADDR"></tt>, <tt><ref id=".WORD" @@ -1985,7 +2022,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .align 256 + .align 256 </verb></tscreen> Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/ @@ -2040,7 +2077,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - Msg: .asciiz "Hello world" + Msg: .asciiz "Hello world" </verb></tscreen> This will put the string "Hello world" followed by a binary zero into @@ -2062,7 +2099,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .assert * = $8000, error, "Code not at $8000" + .assert * = $8000, error, "Code not at $8000" </verb></tscreen> The example assertion will check that the current location is at $8000, @@ -2094,7 +2131,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .autoimport + ; Switch on auto import + .autoimport + ; Switch on auto import </verb></tscreen> <sect1><tt>.BANKBYTES</tt><label id=".BANKBYTES"><p> @@ -2108,17 +2145,17 @@ Here's a list of all control commands and a description, what they do: <tscreen><verb> .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 - TableLookupLo: .lobytes MyTable - TableLookupHi: .hibytes MyTable - TableLookupBank: .bankbytes MyTable + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable + TableLookupBank: .bankbytes MyTable </verb></tscreen> which is equivalent to <tscreen><verb> TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 - TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 - TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + TableLookupBank: .byte ^TableItem0, ^TableItem1, ^TableItem2, ^TableItem3 </verb></tscreen> See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, @@ -2132,7 +2169,7 @@ Here's a list of all control commands and a description, what they do: so this is a shortcut for <tscreen><verb> - .segment "BSS" + .segment "BSS" </verb></tscreen> See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. @@ -2146,8 +2183,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .byte "Hello " - .byt "world", $0D, $00 + .byte "Hello " + .byt "world", $0D, $00 </verb></tscreen> @@ -2162,23 +2199,22 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .case - ; Identifiers are not case sensitive + .case - ; Identifiers are not case sensitive </verb></tscreen> <sect1><tt>.CHARMAP</tt><label id=".CHARMAP"><p> Apply a custom mapping for characters. The command is followed by two - numbers. The first one is the index of the source character (range 1..255), + numbers. The first one is the index of the source character (range 0..255); the second one is the mapping (range 0..255). The mapping applies to all - character and string constants when they generate output, and overrides a - mapping table specified with the <tt><ref id="option-t" name="-t"></tt> + character and string constants <em/when/ they generate output; and, overrides + a mapping table specified with the <tt><ref id="option-t" name="-t"></tt> command line switch. Example: - <tscreen><verb> - .charmap $41, $61 ; Map 'A' to 'a' + .charmap $41, $61 ; Map 'A' to 'a' </verb></tscreen> @@ -2188,7 +2224,7 @@ Here's a list of all control commands and a description, what they do: "CODE", so this is a shortcut for <tscreen><verb> - .segment "CODE" + .segment "CODE" </verb></tscreen> See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. @@ -2224,8 +2260,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .condes ModuleInit, constructor - .condes ModInit, 0, 16 + .condes ModuleInit, constructor + .condes ModInit, 0, 16 </verb></tscreen> See the <tt><ref id=".CONSTRUCTOR" name=".CONSTRUCTOR"></tt>, <tt><ref @@ -2256,8 +2292,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .constructor ModuleInit - .constructor ModInit, 16 + .constructor ModuleInit + .constructor ModInit, 16 </verb></tscreen> See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref @@ -2272,7 +2308,7 @@ Here's a list of all control commands and a description, what they do: "DATA", so this is a shortcut for <tscreen><verb> - .segment "DATA" + .segment "DATA" </verb></tscreen> See also the <tt><ref id=".SEGMENT" name=".SEGMENT"></tt> command. @@ -2287,13 +2323,13 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .dbyt $1234, $4512 + .dbyt $1234, $4512 </verb></tscreen> This will emit the bytes <tscreen><verb> - $12 $34 $45 $12 + $12 $34 $45 $12 </verb></tscreen> into the current segment in that order. @@ -2310,7 +2346,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .debuginfo + ; Generate debug info + .debuginfo + ; Generate debug info </verb></tscreen> @@ -2351,15 +2387,15 @@ Here's a list of all control commands and a description, what they do: <tt><ref id=".IFDEF" name=".IFDEF"></tt> statement may be replaced by <tscreen><verb> - .if .defined(a) + .if .defined(a) </verb></tscreen> <sect1><tt>.DEFINEDMACRO</tt><label id=".DEFINEDMACRO"><p> Builtin function. The function expects an identifier as argument in braces. - The argument is evaluated, and the function yields "true" if the identifier - has already been defined as the name of a macro. Otherwise the function yields + The argument is evaluated, and the function yields "true" if the identifier + has already been defined as the name of a macro. Otherwise the function yields false. Example: <tscreen><verb> @@ -2367,8 +2403,8 @@ Here's a list of all control commands and a description, what they do: clc adc foo .endmacro - - .if .definedmacro(add) + + .if .definedmacro(add) add #$01 .else clc @@ -2398,8 +2434,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .destructor ModuleDone - .destructor ModDone, 16 + .destructor ModuleDone + .destructor ModDone, 16 </verb></tscreen> See the <tt><ref id=".CONDES" name=".CONDES"></tt> and <tt><ref @@ -2416,7 +2452,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .dword $12344512, $12FA489 + .dword $12344512, $12FA489 </verb></tscreen> @@ -2559,13 +2595,13 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .if foo = 1 - ... - .elseif bar = 1 - ... - .else - .error "Must define foo or bar!" - .endif + .if foo = 1 + ... + .elseif bar = 1 + ... + .else + .error "Must define foo or bar!" + .endif </verb></tscreen> See also: <tt><ref id=".FATAL" name=".FATAL"></tt>, @@ -2598,7 +2634,7 @@ Here's a list of all control commands and a description, what they do: Examples: <tscreen><verb> - .export foo + .export foo .export bar: far .export foobar: far = foo * bar .export baz := foobar, zap: far = baz - bar @@ -2621,7 +2657,7 @@ Here's a list of all control commands and a description, what they do: Examples: <tscreen><verb> - .exportzp foo, bar + .exportzp foo, bar .exportzp baz := $02 </verb></tscreen> @@ -2636,7 +2672,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .faraddr DrawCircle, DrawRectangle, DrawHexagon + .faraddr DrawCircle, DrawRectangle, DrawHexagon </verb></tscreen> See: <tt><ref id=".ADDR" name=".ADDR"></tt> @@ -2654,13 +2690,13 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .if foo = 1 - ... - .elseif bar = 1 - ... - .else - .fatal "Must define foo or bar!" - .endif + .if foo = 1 + ... + .elseif bar = 1 + ... + .else + .fatal "Must define foo or bar!" + .endif </verb></tscreen> See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, @@ -2677,7 +2713,7 @@ Here's a list of all control commands and a description, what they do: enabled it, so using <tscreen><verb> - .FEATURE xxx + .FEATURE xxx </verb></tscreen> will enable the feature until end of assembly is reached. @@ -2694,10 +2730,26 @@ Here's a list of all control commands and a description, what they do: <tag><tt>at_in_identifiers</tt><label id="at_in_identifiers"></tag> - Accept the at character (`@') as a valid character in identifiers. The + Accept the at character ('@') as a valid character in identifiers. The at character is not allowed to start an identifier, even with this feature enabled. + <tag><tt>bracket_as_indirect</tt><label id="bracket_as_indirect"></tag> + + Use <tt>[]</tt> instead of <tt>()</tt> for the indirect addressing modes. + Example: + + <tscreen><verb> + lda [$82] + lda [$82,x] + lda [$82],y + jmp [$fffe] + jmp [table,x] + </verb></tscreen> + <em/Note:/ This should not be used in 65186 mode because it conflicts with + the 65816 instruction syntax for far addressing. See the section covering + <tt/<ref id="address-sizes" name="address sizes">/ for more information. + <tag><tt>c_comments</tt><label id="c_comments"></tag> Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right @@ -2713,13 +2765,13 @@ Here's a list of all control commands and a description, what they do: <tag><tt>dollar_in_identifiers</tt><label id="dollar_in_identifiers"></tag> - Accept the dollar sign (`$') as a valid character in identifiers. The + Accept the dollar sign ('$') as a valid character in identifiers. The dollar character is not allowed to start an identifier, even with this feature enabled. <tag><tt>dollar_is_pc</tt><label id="dollar_is_pc"></tag> - The dollar sign may be used as an alias for the star (`*'), which + The dollar sign may be used as an alias for the star ('*'), which gives the value of the current PC in expressions. Note: Assignment to the pseudo variable is not allowed. @@ -2737,7 +2789,7 @@ Here's a list of all control commands and a description, what they do: <tag><tt>leading_dot_in_identifiers</tt><label id="leading_dot_in_identifiers"></tag> - Accept the dot (`.') as the first character of an identifier. This may be + Accept the dot ('.') as the first character of an identifier. This may be used for example to create macro names that start with a dot emulating control directives of other assemblers. Note however, that none of the reserved keywords built into the assembler, that starts with a dot, may be @@ -2773,12 +2825,29 @@ Here's a list of all control commands and a description, what they do: <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag> - Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/ + Allow assignments to the PC symbol ('*' or '$' if <tt/dollar_is_pc/ is enabled). Such an assignment is handled identical to the <tt><ref id=".ORG" name=".ORG"></tt> command (which is usually not needed, so just removing the lines with the assignments may also be an option when porting code written for older assemblers). + <tag><tt>string_escapes</tt><label id="string_escapes"></tag> + + Allow C-style backslash escapes within string constants to embed + special characters. The following escapes are accepted: + <itemize> + <item><tt>\\</tt> backslash (<tt>$5C</tt>) + <item><tt>\'</tt> single quote (<tt>$27</tt>) + <item><tt>\"</tt> double quote (<tt>$22</tt>) + <item><tt>\t</tt> tab (<tt>$09</tt>) + <item><tt>\r</tt> carriage return (<tt>$0D</tt>) + <item><tt>\n</tt> newline (<tt>$0A</tt>) + <item><tt>\xNN</tt> (<tt>$NN</tt>) + </itemize> + + Note that string escapes are converted to platform-specific characters in + the same way that other characters are converted. + <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag> Allow the use of instructions names as names for macros and symbols. This @@ -2808,7 +2877,7 @@ Here's a list of all control commands and a description, what they do: assembler, the features <verb> - labels_without_colons, pc_assignment, loose_char_term + labels_without_colons, pc_assignment, loose_char_term </verb> may be helpful. They do not make ca65 completely compatible, so you may not @@ -2828,9 +2897,9 @@ Here's a list of all control commands and a description, what they do: The command is followed by one of the keywords <tscreen><verb> - author - comment - compiler + author + comment + compiler </verb></tscreen> a comma and a string. The option is written into the object file @@ -2841,9 +2910,9 @@ Here's a list of all control commands and a description, what they do: Examples: <tscreen><verb> - .fileopt comment, "Code stolen from my brother" - .fileopt compiler, "BASIC 2.0" - .fopt author, "J. R. User" + .fileopt comment, "Code stolen from my brother" + .fileopt compiler, "BASIC 2.0" + .fopt author, "J. R. User" </verb></tscreen> @@ -2859,7 +2928,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .forceimport needthisone, needthistoo + .forceimport needthisone, needthistoo </verb></tscreen> See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> @@ -2876,7 +2945,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .global foo, bar + .global foo, bar </verb></tscreen> @@ -2892,7 +2961,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .globalzp foo, bar + .globalzp foo, bar </verb></tscreen> <sect1><tt>.HIBYTES</tt><label id=".HIBYTES"><p> @@ -2905,14 +2974,14 @@ Here's a list of all control commands and a description, what they do: <tscreen><verb> .lobytes $1234, $2345, $3456, $4567 - .hibytes $fedc, $edcb, $dcba, $cba9 + .hibytes $fedc, $edcb, $dcba, $cba9 </verb></tscreen> which is equivalent to <tscreen><verb> .byte $34, $45, $56, $67 - .byte $fe, $ed, $dc, $cb + .byte $fe, $ed, $dc, $cb </verb></tscreen> Example: @@ -2920,15 +2989,15 @@ Here's a list of all control commands and a description, what they do: <tscreen><verb> .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 - TableLookupLo: .lobytes MyTable - TableLookupHi: .hibytes MyTable + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable </verb></tscreen> which is equivalent to <tscreen><verb> TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 - TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 </verb></tscreen> See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, @@ -2973,7 +3042,7 @@ Here's a list of all control commands and a description, what they do: Conditional assembly: Check if there are any remaining tokens in this line, and evaluate to FALSE if this is the case, and to TRUE otherwise. If the condition is not true, further lines are not assembled until an <tt><ref - id=".ELSE" name=".ESLE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or + id=".ELSE" name=".ELSE"></tt>, <tt><ref id=".ELSEIF" name=".ELSEIF"></tt> or <tt><ref id=".ENDIF" name=".ENDIF"></tt> directive. This command is often used to check if a macro parameter was given. Since an @@ -2983,13 +3052,13 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .macro arg1, arg2 - .ifblank arg2 - lda #arg1 - .else - lda #arg2 - .endif - .endmacro + .macro arg1, arg2 + .ifblank arg2 + lda #arg1 + .else + lda #arg2 + .endif + .endmacro </verb></tscreen> See also: <tt><ref id=".BLANK" name=".BLANK"></tt> @@ -3031,12 +3100,12 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .macro arg1, arg2 - lda #arg1 - .ifnblank arg2 - lda #arg2 - .endif - .endmacro + .macro arg1, arg2 + lda #arg1 + .ifnblank arg2 + lda #arg2 + .endif + .endmacro </verb></tscreen> See also: <tt><ref id=".BLANK" name=".BLANK"></tt> @@ -3066,6 +3135,12 @@ Here's a list of all control commands and a description, what they do: (see <tt><ref id=".P02" name=".P02"></tt> command). +<sect1><tt>.IFP4510</tt><label id=".IFP4510"><p> + + Conditional assembly: Check if the assembler is currently in 4510 mode + (see <tt><ref id=".P4510" name=".P4510"></tt> command). + + <sect1><tt>.IFP816</tt><label id=".IFP816"><p> Conditional assembly: Check if the assembler is currently in 65816 mode @@ -3096,11 +3171,11 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .ifref ToHex ; If someone used this subroutine - ToHex: tay ; Define subroutine - lda HexTab,y - rts - .endif + .ifref ToHex ; If someone used this subroutine + ToHex: tay ; Define subroutine + lda HexTab,y + rts + .endif </verb></tscreen> See also: <tt><ref id=".REFERENCED" name=".REFERENCED"></tt> @@ -3115,7 +3190,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .import foo + .import foo .import bar: zeropage </verb></tscreen> @@ -3131,7 +3206,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .importzp foo, bar + .importzp foo, bar </verb></tscreen> See: <tt><ref id=".IMPORT" name=".IMPORT"></tt> @@ -3149,14 +3224,14 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - ; Include whole file - .incbin "sprites.dat" + ; Include whole file + .incbin "sprites.dat" - ; Include file starting at offset 256 - .incbin "music.dat", $100 + ; Include file starting at offset 256 + .incbin "music.dat", $100 - ; Read 100 bytes starting at offset 200 - .incbin "graphics.dat", 200, 100 + ; Read 100 bytes starting at offset 200 + .incbin "graphics.dat", 200, 100 </verb></tscreen> @@ -3167,7 +3242,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .include "subs.inc" + .include "subs.inc" </verb></tscreen> @@ -3192,8 +3267,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .interruptor IrqHandler - .interruptor Handler, 16 + .interruptor IrqHandler + .interruptor Handler, 16 </verb></tscreen> See the <tt><ref id=".CONDES" name=".CONDES"></tt> command and the separate @@ -3209,12 +3284,12 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .if .not .ismnemonic(ina) - .macro ina - clc - adc #$01 - .endmacro - .endif + .if .not .ismnemonic(ina) + .macro ina + clc + adc #$01 + .endmacro + .endif </verb></tscreen> @@ -3231,10 +3306,10 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .linecont + ; Allow line continuations + .linecont + ; Allow line continuations - lda \ - #$20 ; This is legal now + lda \ + #$20 ; This is legal now </verb></tscreen> @@ -3252,7 +3327,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .list on ; Enable listing output + .list on ; Enable listing output </verb></tscreen> @@ -3267,9 +3342,9 @@ Here's a list of all control commands and a description, what they do: Examples: <tscreen><verb> - .listbytes unlimited ; List all bytes - .listbytes 12 ; List the first 12 bytes - .incbin "data.bin" ; Include large binary file + .listbytes unlimited ; List all bytes + .listbytes 12 ; List the first 12 bytes + .incbin "data.bin" ; Include large binary file </verb></tscreen> @@ -3283,14 +3358,14 @@ Here's a list of all control commands and a description, what they do: <tscreen><verb> .lobytes $1234, $2345, $3456, $4567 - .hibytes $fedc, $edcb, $dcba, $cba9 + .hibytes $fedc, $edcb, $dcba, $cba9 </verb></tscreen> which is equivalent to <tscreen><verb> .byte $34, $45, $56, $67 - .byte $fe, $ed, $dc, $cb + .byte $fe, $ed, $dc, $cb </verb></tscreen> Example: @@ -3298,15 +3373,15 @@ Here's a list of all control commands and a description, what they do: <tscreen><verb> .define MyTable TableItem0, TableItem1, TableItem2, TableItem3 - TableLookupLo: .lobytes MyTable - TableLookupHi: .hibytes MyTable + TableLookupLo: .lobytes MyTable + TableLookupHi: .hibytes MyTable </verb></tscreen> which is equivalent to <tscreen><verb> TableLookupLo: .byte <TableItem0, <TableItem1, <TableItem2, <TableItem3 - TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 + TableLookupHi: .byte >TableItem0, >TableItem1, >TableItem2, >TableItem3 </verb></tscreen> See also: <tt><ref id=".BYTE" name=".BYTE"></tt>, @@ -3347,15 +3422,15 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .localchar '?' - - Clear: lda #$00 ; Global label - ?Loop: sta Mem,y ; Local label - dey - bne ?Loop ; Ok - rts - Sub: ... ; New global label - bne ?Loop ; ERROR: Unknown identifier! + .localchar '?' + + Clear: lda #$00 ; Global label + ?Loop: sta Mem,y ; Local label + dey + bne ?Loop ; Ok + rts + Sub: ... ; New global label + bne ?Loop ; ERROR: Unknown identifier! </verb></tscreen> @@ -3379,10 +3454,10 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .macpack longbranch ; Include macro package + .macpack longbranch ; Include macro package - cmp #$20 ; Set condition codes - jne Label ; Jump long on condition + cmp #$20 ; Set condition codes + jne Label ; Jump long on condition </verb></tscreen> Macro packages are explained in more detail in section <ref @@ -3399,7 +3474,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .macro ldax arg ; Define macro ldax + .macro ldax arg ; Define macro ldax lda arg ldx arg+1 </verb></tscreen> @@ -3429,7 +3504,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .org $7FF ; Emit code starting at $7FF + .org $7FF ; Emit code starting at $7FF </verb></tscreen> @@ -3442,7 +3517,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .out "This code was written by the codebuster(tm)" + .out "This code was written by the codebuster(tm)" </verb></tscreen> See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, @@ -3457,7 +3532,18 @@ Here's a list of all control commands and a description, what they do: <tt><ref id="option--cpu" name="--cpu"></tt> command line option. See: <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + name=".PSC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and + <tt><ref id=".P4510" name=".P4510"></tt> + + +<sect1><tt>.P4510</tt><label id=".P4510"><p> + + Enable the 4510 instruction set. This is a superset of the 65C02 and + 6502 instruction sets. + + See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" + name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt> and + <tt><ref id=".P816" name=".P816"></tt> <sect1><tt>.P816</tt><label id=".P816"><p> @@ -3466,7 +3552,8 @@ Here's a list of all control commands and a description, what they do: 6502 instruction sets. See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt> and <tt><ref id=".PC02" name=".PC02"></tt> + name=".PSC02"></tt>, <tt><ref id=".PC02" name=".PC02"></tt> and + <tt><ref id=".P4510" name=".P4510"></tt> <sect1><tt>.PAGELEN, .PAGELENGTH</tt><label id=".PAGELENGTH"><p> @@ -3482,9 +3569,9 @@ Here's a list of all control commands and a description, what they do: Examples: <tscreen><verb> - .pagelength 66 ; Use 66 lines per listing page + .pagelength 66 ; Use 66 lines per listing page - .pagelength unlimited ; Unlimited page length + .pagelength unlimited ; Unlimited page length </verb></tscreen> @@ -3494,7 +3581,8 @@ Here's a list of all control commands and a description, what they do: 6502 and 65SC02 instructions. See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PSC02" - name=".PSC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + name=".PSC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and + <tt><ref id=".P4510" name=".P4510"></tt> <sect1><tt>.POPCPU</tt><label id=".POPCPU"><p> @@ -3546,15 +3634,15 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .proc Clear ; Define Clear subroutine, start new level - lda #$00 - L1: sta Mem,y ; L1 is local and does not cause a - ; duplicate symbol error if used in other - ; places - dey - bne L1 ; Reference local symbol - rts - .endproc ; Leave lexical level + .proc Clear ; Define Clear subroutine, start new level + lda #$00 + L1: sta Mem,y ; L1 is local and does not cause a + ; duplicate symbol error if used in other + ; places + dey + bne L1 ; Reference local symbol + rts + .endproc ; Leave lexical level </verb></tscreen> See: <tt/<ref id=".ENDPROC" name=".ENDPROC">/ and <tt/<ref id=".SCOPE" @@ -3567,7 +3655,8 @@ Here's a list of all control commands and a description, what they do: 6502 instructions. See: <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".PC02" - name=".PC02"></tt> and <tt><ref id=".P816" name=".P816"></tt> + name=".PC02"></tt>, <tt><ref id=".P816" name=".P816"></tt> and + <tt><ref id=".P4510" name=".P4510"></tt> <sect1><tt>.PUSHCPU</tt><label id=".PUSHCPU"><p> @@ -3628,11 +3717,11 @@ Here's a list of all control commands and a description, what they do: characters of the string are XORed by the value $55. <tscreen><verb> - .macro Crypt Arg - .repeat .strlen(Arg), I - .byte .strat(Arg, I) ^ $55 - .endrep - .endmacro + .macro Crypt Arg + .repeat .strlen(Arg), I + .byte .strat(Arg, I) ^ $55 + .endrep + .endmacro </verb></tscreen> See: <tt><ref id=".ENDREPEAT" name=".ENDREPEAT"></tt> @@ -3650,8 +3739,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - ; Reserve 12 bytes of memory with value $AA - .res 12, $AA + ; Reserve 12 bytes of memory with value $AA + .res 12, $AA </verb></tscreen> @@ -3661,7 +3750,7 @@ Here's a list of all control commands and a description, what they do: "RODATA", so this is a shortcut for <tscreen><verb> - .segment "RODATA" + .segment "RODATA" </verb></tscreen> The RODATA segment is a segment that is used by the compiler for @@ -3689,11 +3778,11 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .scope Error ; Start new scope named Error + .scope Error ; Start new scope named Error None = 0 ; No error File = 1 ; File error Parse = 2 ; Parse error - .endscope ; Close lexical level + .endscope ; Close lexical level ... lda #Error::File ; Use symbol from scope Error @@ -3727,7 +3816,7 @@ Here's a list of all control commands and a description, what they do: page and direct (short) addressing is possible for data in this segment. Beware: Only labels in a segment with the zeropage attribute are marked - as reachable by short addressing. The `*' (PC counter) operator will + as reachable by short addressing. The '*' (PC counter) operator will work as in other segments and will create absolute variable values. Please note that a segment cannot have two different address sizes. A @@ -3736,10 +3825,10 @@ Here's a list of all control commands and a description, what they do: Examples: <tscreen><verb> - .segment "ROM2" ; Switch to ROM2 segment - .segment "ZP2": zeropage ; New direct segment - .segment "ZP2" ; Ok, will use last attribute - .segment "ZP2": absolute ; Error, redecl mismatch + .segment "ROM2" ; Switch to ROM2 segment + .segment "ZP2": zeropage ; New direct segment + .segment "ZP2" ; Ok, will use last attribute + .segment "ZP2": absolute ; Error, redecl mismatch </verb></tscreen> See: <tt><ref id=".BSS" name=".BSS"></tt>, <tt><ref id=".CODE" @@ -3759,7 +3848,7 @@ Here's a list of all control commands and a description, what they do: Switch the CPU instruction set. The command is followed by a string that specifies the CPU. Possible values are those that can also be supplied to the <tt><ref id="option--cpu" name="--cpu"></tt> command line option, - namely: 6502, 6502X, 65SC02, 65C02, 65816 and HuC6280. + namely: 6502, 6502X, 65SC02, 65C02, 65816, 4510 and HuC6280. See: <tt><ref id=".CPU" name=".CPU"></tt>, <tt><ref id=".IFP02" name=".IFP02"></tt>, @@ -3768,6 +3857,7 @@ Here's a list of all control commands and a description, what they do: <tt><ref id=".IFPSC02" name=".IFPSC02"></tt>, <tt><ref id=".P02" name=".P02"></tt>, <tt><ref id=".P816" name=".P816"></tt>, + <tt><ref id=".P4510" name=".P4510"></tt>, <tt><ref id=".PC02" name=".PC02"></tt>, <tt><ref id=".PSC02" name=".PSC02"></tt> @@ -3798,8 +3888,8 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .smart ; Be smart - .smart - ; Stop being smart + .smart ; Be smart + .smart - ; Stop being smart </verb></tscreen> See: <tt><ref id=".A16" name=".A16"></tt>, @@ -3869,17 +3959,17 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .macro jne target - .local L1 - .ifndef target - .warning "Forward jump in jne, cannot optimize!" - beq L1 - jmp target - L1: - .else - ... - .endif - .endmacro + .macro jne target + .local L1 + .ifndef target + .warning "Forward jump in jne, cannot optimize!" + beq L1 + jmp target + L1: + .else + ... + .endif + .endmacro </verb></tscreen> See also: <tt><ref id=".ERROR" name=".ERROR"></tt>, @@ -3895,7 +3985,7 @@ Here's a list of all control commands and a description, what they do: Example: <tscreen><verb> - .word $0D00, $AF13, _Clear + .word $0D00, $AF13, _Clear </verb></tscreen> @@ -3935,10 +4025,10 @@ In its simplest form, a macro does not have parameters. Here's an example: <tscreen><verb> - .macro asr ; Arithmetic shift right - cmp #$80 ; Put bit 7 into carry - ror ; Rotate right with carry - .endmacro +.macro asr ; Arithmetic shift right + cmp #$80 ; Put bit 7 into carry + ror ; Rotate right with carry +.endmacro </verb></tscreen> The macro above consists of two real instructions, that are inserted into @@ -3946,9 +4036,9 @@ the code, whenever the macro is expanded. Macro expansion is simply done by using the name, like this: <tscreen><verb> - lda $2010 - asr - sta $2010 + lda $2010 + asr + sta $2010 </verb></tscreen> @@ -3957,15 +4047,15 @@ by using the name, like this: When using macro parameters, macros can be even more useful: <tscreen><verb> - .macro inc16 addr - clc - lda addr - adc #$01 - sta addr - lda addr+1 - adc #$00 - sta addr+1 - .endmacro +.macro inc16 addr + clc + lda addr + adc #<$0001 + sta addr + lda addr+1 + adc #>$0001 + sta addr+1 +.endmacro </verb></tscreen> When calling the macro, you may give a parameter, and each occurrence of @@ -3973,19 +4063,19 @@ the name "addr" in the macro definition will be replaced by the given parameter. So <tscreen><verb> - inc16 $1000 + inc16 $1000 </verb></tscreen> will be expanded to <tscreen><verb> - clc - lda $1000 - adc #$01 - sta $1000 - lda $1000+1 - adc #$00 - sta $1000+1 + clc + lda $1000 + adc #<$0001 + sta $1000 + lda $1000+1 + adc #>$0001 + sta $1000+1 </verb></tscreen> A macro may have more than one parameter, in this case, the parameters @@ -4006,40 +4096,40 @@ opposite. Look at this example: <tscreen><verb> - .macro ldaxy a, x, y - .ifnblank a - lda #a - .endif - .ifnblank x - ldx #x - .endif - .ifnblank y - ldy #y - .endif - .endmacro +.macro ldaxy a, x, y +.ifnblank a + lda #a +.endif +.ifnblank x + ldx #x +.endif +.ifnblank y + ldy #y +.endif +.endmacro </verb></tscreen> -This macro may be called as follows: +That macro may be called as follows: <tscreen><verb> - ldaxy 1, 2, 3 ; Load all three registers + ldaxy 1, 2, 3 ; Load all three registers - ldaxy 1, , 3 ; Load only a and y + ldaxy 1, , 3 ; Load only a and y - ldaxy , , 3 ; Load y only + ldaxy , , 3 ; Load y only </verb></tscreen> -There's another helper command for determining, which macro parameters are -valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt> This command is -replaced by the parameter count given, <em/including/ intermediate empty macro +There's another helper command for determining which macro parameters are +valid: <tt><ref id=".PARAMCOUNT" name=".PARAMCOUNT"></tt>. That command is +replaced by the parameter count given, <em/including/ explicitly empty parameters: <tscreen><verb> - ldaxy 1 ; .PARAMCOUNT = 1 - ldaxy 1,,3 ; .PARAMCOUNT = 3 - ldaxy 1,2 ; .PARAMCOUNT = 2 - ldaxy 1, ; .PARAMCOUNT = 2 - ldaxy 1,2,3 ; .PARAMCOUNT = 3 + ldaxy 1 ; .PARAMCOUNT = 1 + ldaxy 1,,3 ; .PARAMCOUNT = 3 + ldaxy 1,2 ; .PARAMCOUNT = 2 + ldaxy 1, ; .PARAMCOUNT = 2 + ldaxy 1,2,3 ; .PARAMCOUNT = 3 </verb></tscreen> Macro parameters may optionally be enclosed into curly braces. This allows the @@ -4047,19 +4137,19 @@ inclusion of tokens that would otherwise terminate the parameter (the comma in case of a macro parameter). <tscreen><verb> - .macro foo arg1, arg2 - ... - .endmacro +.macro foo arg1, arg2 + ... +.endmacro - foo ($00,x) ; Two parameters passed - foo {($00,x)} ; One parameter passed + foo ($00,x) ; Two parameters passed + foo {($00,x)} ; One parameter passed </verb></tscreen> In the first case, the macro is called with two parameters: '<tt/($00/' -and 'x)'. The comma is not passed to the macro, since it is part of the +and '<tt/x)/'. The comma is not passed to the macro, because it is part of the calling sequence, not the parameters. -In the second case, '($00,x)' is passed to the macro, this time +In the second case, '<tt/($00,x)/' is passed to the macro; this time, including the comma. @@ -4072,17 +4162,17 @@ id=".MATCH" name=".MATCH">/ and <tt/<ref id=".XMATCH" name=".XMATCH">/ functions will allow you to do exactly this: <tscreen><verb> - .macro ldax arg - .if (.match (.left (1, {arg}), #)) - ; immediate mode - lda #<(.right (.tcount ({arg})-1, {arg})) - ldx #>(.right (.tcount ({arg})-1, {arg})) - .else - ; assume absolute or zero page - lda arg - ldx 1+(arg) - .endif - .endmacro +.macro ldax arg + .if (.match (.left (1, {arg}), #)) + ; immediate mode + lda #<(.right (.tcount ({arg})-1, {arg})) + ldx #>(.right (.tcount ({arg})-1, {arg})) + .else + ; assume absolute or zero page + lda arg + ldx 1+(arg) + .endif +.endmacro </verb></tscreen> Using the <tt/<ref id=".MATCH" name=".MATCH">/ function, the macro is able to @@ -4096,11 +4186,11 @@ as end-of-list. The macro can be used as <tscreen><verb> - foo: .word $5678 - ... - ldax #$1234 ; X=$12, A=$34 - ... - ldax foo ; X=$56, A=$78 +foo: .word $5678 +... + ldax #$1234 ; X=$12, A=$34 +... + ldax foo ; X=$56, A=$78 </verb></tscreen> @@ -4109,38 +4199,38 @@ The macro can be used as Macros may be used recursively: <tscreen><verb> - .macro push r1, r2, r3 - lda r1 - pha - .if .paramcount > 1 - push r2, r3 - .endif - .endmacro +.macro push r1, r2, r3 + lda r1 + pha +.ifnblank r2 + push r2, r3 +.endif +.endmacro </verb></tscreen> -There's also a special macro to help writing recursive macros: <tt><ref -id=".EXITMACRO" name=".EXITMACRO"></tt> This command will stop macro expansion -immediately: +There's also a special macro command to help with writing recursive macros: +<tt><ref id=".EXITMACRO" name=".EXITMACRO"></tt>. That command will stop macro +expansion immediately: <tscreen><verb> - .macro push r1, r2, r3, r4, r5, r6, r7 - .ifblank r1 - ; First parameter is empty - .exitmacro - .else - lda r1 - pha - .endif - push r2, r3, r4, r5, r6, r7 - .endmacro +.macro push r1, r2, r3, r4, r5, r6, r7 +.ifblank r1 + ; First parameter is empty + .exitmacro +.else + lda r1 + pha +.endif + push r2, r3, r4, r5, r6, r7 +.endmacro </verb></tscreen> -When expanding this macro, the expansion will push all given parameters +When expanding that macro, the expansion will push all given parameters until an empty one is encountered. The macro may be called like this: <tscreen><verb> - push $20, $21, $32 ; Push 3 ZP locations - push $21 ; Push one ZP location + push $20, $21, $32 ; Push 3 ZP locations + push $21 ; Push one ZP location </verb></tscreen> @@ -4151,27 +4241,27 @@ Now, with recursive macros, <tt><ref id=".IFBLANK" name=".IFBLANK"></tt> and Have a look at the inc16 macro above. Here is it again: <tscreen><verb> - .macro inc16 addr - clc - lda addr - adc #$01 - sta addr - lda addr+1 - adc #$00 - sta addr+1 - .endmacro +.macro inc16 addr + clc + lda addr + adc #<$0001 + sta addr + lda addr+1 + adc #>$0001 + sta addr+1 +.endmacro </verb></tscreen> If you have a closer look at the code, you will notice, that it could be written more efficiently, like this: <tscreen><verb> - .macro inc16 addr - inc addr - bne Skip - inc addr+1 - Skip: - .endmacro +.macro inc16 addr + inc addr + bne Skip + inc addr+1 +Skip: +.endmacro </verb></tscreen> But imagine what happens, if you use this macro twice? Since the label "Skip" @@ -4183,27 +4273,27 @@ local variables are replaced by a unique name in each separate macro expansion. So we can solve the problem above by using <tt/.LOCAL/: <tscreen><verb> - .macro inc16 addr - .local Skip ; Make Skip a local symbol - inc addr - bne Skip - inc addr+1 - Skip: ; Not visible outside - .endmacro +.macro inc16 addr + .local Skip ; Make Skip a local symbol + inc addr + bne Skip + inc addr+1 +Skip: ; Not visible outside +.endmacro </verb></tscreen> Another solution is of course to start a new lexical block inside the macro that hides any labels: <tscreen><verb> - .macro inc16 addr - .proc - inc addr - bne Skip - inc addr+1 - Skip: - .endproc - .endmacro +.macro inc16 addr +.proc + inc addr + bne Skip + inc addr+1 +Skip: +.endproc +.endmacro </verb></tscreen> @@ -4216,34 +4306,41 @@ different: <itemize> -<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not - span more than a line. You may use line continuation (see <tt><ref - id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over - more than one line for increased readability, but the macro itself - may not contain an end-of-line token. - -<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share - the name space with classic macros, but they are detected and replaced - at the scanner level. While classic macros may be used in every place, - where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE" - name=".DEFINE"></tt> style macros are allowed anywhere in a line. So - they are more versatile in some situations. - -<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take - parameters. While classic macros may have empty parameters, this is - not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros. - For this macro type, the number of actual parameters must match - exactly the number of formal parameters. - - To make this possible, formal parameters are enclosed in braces when - defining the macro. If there are no parameters, the empty braces may - be omitted. - -<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not - contain end-of-line tokens, there are things that cannot be done. They - may not contain several processor instructions for example. So, while - some things may be done with both macro types, each type has special - usages. The types complement each other. +<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> may not + span more than a line. You may use line continuation (see <tt><ref + id=".LINECONT" name=".LINECONT"></tt>) to spread the definition over + more than one line for increased readability, but the macro itself + may not contain an end-of-line token. + +<item> Macros defined with <tt><ref id=".DEFINE" name=".DEFINE"></tt> share + the name space with classic macros, but they are detected and replaced + at the scanner level. While classic macros may be used in every place, + where a mnemonic or other directive is allowed, <tt><ref id=".DEFINE" + name=".DEFINE"></tt> style macros are allowed anywhere in a line. So + they are more versatile in some situations. + +<item> <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may take + parameters. While classic macros may have empty parameters, this is + not true for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros. + For this macro type, the number of actual parameters must match + exactly the number of formal parameters. + + To make this possible, formal parameters are enclosed in braces when + defining the macro. If there are no parameters, the empty braces may + be omitted. + +<item> Since <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros may not + contain end-of-line tokens, there are things that cannot be done. They + may not contain several processor instructions for example. So, while + some things may be done with both macro types, each type has special + usages. The types complement each other. + +<item> Parentheses work differently from C macros. + The common practice of wrapping C macros in parentheses may cause + unintended problems here, such as accidentally implying an + indirect addressing mode. While the definition of a macro requires + parentheses around its argument list, when invoked they should not be + included. </itemize> @@ -4254,41 +4351,65 @@ To emulate assemblers that use "<tt/EQU/" instead of "<tt/=/" you may use the following <tt/.DEFINE/: <tscreen><verb> - .define EQU = +.define EQU = - foo EQU $1234 ; This is accepted now +foo EQU $1234 ; This is accepted now </verb></tscreen> You may use the directive to define string constants used elsewhere: <tscreen><verb> - ; Define the version number - .define VERSION "12.3a" +; Define the version number +.define VERSION "12.3a" - ; ... and use it - .asciiz VERSION + ; ... and use it + .asciiz VERSION </verb></tscreen> Macros with parameters may also be useful: <tscreen><verb> - .define DEBUG(message) .out message +.define DEBUG(message) .out message - DEBUG "Assembling include file #3" + DEBUG "Assembling include file #3" </verb></tscreen> -Note that, while formal parameters have to be placed in braces, this is -not true for the actual parameters. Beware: Since the assembler cannot -detect the end of one parameter, only the first token is used. If you -don't like that, use classic macros instead: +Note that, while formal parameters have to be placed in parentheses, +the actual argument used when invoking the macro should not be. +The invoked arguments are separated by commas only, if parentheses are +used by accident they will become part of the replaced token. + +If you wish to have an expression follow the macro invocation, the +last parameter can be enclosed in curly braces {} to indicate the end of that +argument. + +Examples: <tscreen><verb> - .macro DEBUG message - .out message - .endmacro +.define COMBINE(ta,tb,tc) ta+tb*10+tc*100 + +.word COMBINE 5,6,7 ; 5+6*10+7*100 = 765 +.word COMBINE(5,6,7) ; (5+6*10+7)*100 = 7200 ; incorrect use of parentheses +.word COMBINE 5,6,7+1 ; 5+6*10+7+1*100 = 172 +.word COMBINE 5,6,{7}+1 ; 5+6*10+7*100+1 = 766 ; {} encloses the argument +.word COMBINE 5,6-2,7 ; 5+6-2*10+7*100 = 691 +.word COMBINE 5,(6-2),7 ; 5+(6-2)*10+7*100 = 745 +.word COMBINE 5,6,7+COMBINE 0,1,2 ; 5+6*10+7+0+1*10+2*100*100 = 20082 +.word COMBINE 5,6,{7}+COMBINE 0,1,2 ; 5+6*10+7*100+0+1*10+2*100 = 975 </verb></tscreen> -(This is an example where a problem can be solved with both macro types). +With C macros it is common to enclose the results in parentheses to +prevent unintended interactions with the text of the arguments, but +additional care must be taken in this assembly context where parentheses +may alter the meaning of a statement. In particular, indirect addressing modes +may be accidentally implied: + +<tscreen><verb> +.define DUO(ta,tb) (ta+(tb*10)) + + lda DUO(5,4), Y ; LDA (indirect), Y + lda 0+DUO(5,4), Y ; LDA absolute indexed, Y +</verb></tscreen> <sect1>Characters in macros<p> @@ -4308,12 +4429,12 @@ be sure to take the translation into account. <sect1>Deleting macros<p> Macros can be deleted. This will not work if the macro that should be deleted -is currently expanded as in the following non working example: +is currently expanded as in the following non-working example: <tscreen><verb> - .macro notworking - .delmacro notworking - .endmacro +.macro notworking + .delmacro notworking +.endmacro notworking ; Will not work </verb></tscreen> @@ -4324,19 +4445,19 @@ for <tt><ref id=".DEFINE" name=".DEFINE"></tt> style macros, <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> must be used. Example: <tscreen><verb> - .define value 1 - .macro mac - .byte 2 - .endmacro +.define value 1 +.macro mac + .byte 2 +.endmacro - .byte value ; Emit one byte with value 1 - mac ; Emit another byte with value 2 + .byte value ; Emit one byte with value 1 + mac ; Emit another byte with value 2 - .undefine value - .delmacro mac +.undefine value +.delmacro mac - .byte value ; Error: Unknown identifier - mac ; Error: Missing ":" + .byte value ; Error: Unknown identifier + mac ; Error: Missing ":" </verb></tscreen> A separate command for <tt>.DEFINE</tt> style macros was necessary, because @@ -4348,6 +4469,7 @@ argument to <tt>.UNDEFINE</tt> is not allowed to come from another different commands increases flexibility. + <sect>Macro packages<label id="macropackages"><p> Using the <tt><ref id=".MACPACK" name=".MACPACK"></tt> directive, predefined @@ -4362,14 +4484,14 @@ Currently defined macroes are: <tscreen><verb> .macro add Arg ; add without carry - clc - adc Arg - .endmacro + clc + adc Arg + .endmacro .macro sub Arg ; subtract without borrow - sec - sbc Arg - .endmacro + sec + sbc Arg + .endmacro .macro bge Arg ; branch on greater-than or equal bcs Arg @@ -4409,14 +4531,14 @@ definition for the "<tt/jeq/" macro, the other macros are built using the same scheme: <tscreen><verb> - .macro jeq Target - .if .def(Target) .and ((*+2)-(Target) <= 127) - beq Target - .else - bne *+5 - jmp Target - .endif - .endmacro + .macro jeq Target + .if .def(Target) .and ((*+2)-(Target) <= 127) + beq Target + .else + bne *+5 + jmp Target + .endif + .endmacro </verb></tscreen> All macros expand to a short branch, if the label is already defined (back @@ -4427,11 +4549,17 @@ jump to the actual branch target. The package defines the following macros: <tscreen><verb> - jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc + jeq, jne, jmi, jpl, jcs, jcc, jvs, jvc </verb></tscreen> +<sect1><tt>.MACPACK apple2</tt><p> + +This macro package defines a macro named <tt/scrcode/. It takes a string +as argument and places this string into memory translated into screen codes. + + <sect1><tt>.MACPACK atari</tt><p> This macro package defines a macro named <tt/scrcode/. It takes a string @@ -4457,6 +4585,7 @@ each supported CPU a constant similar to CPU_65816 CPU_SWEET16 CPU_HUC6280 + CPU_4510 </verb></tscreen> is defined. These constants may be used to determine the exact type of the @@ -4470,6 +4599,7 @@ another constant is defined: CPU_ISET_65816 CPU_ISET_SWEET16 CPU_ISET_HUC6280 + CPU_ISET_4510 </verb></tscreen> The value read from the <tt/<ref id=".CPU" name=".CPU">/ pseudo variable may @@ -4497,7 +4627,7 @@ it is possible to determine if the instruction is supported, which is the case for the 65SC02, 65C02 and 65816 CPUs (the latter two are upwards compatible to the 65SC02). - + <sect1><tt>.MACPACK module</tt><p> This macro package defines a macro named <tt/module_header/. It takes an @@ -4514,6 +4644,7 @@ compiler, depending on the target system selected: <itemize> <item><tt/__APPLE2__/ - Target system is <tt/apple2/ or <tt/apple2enh/ <item><tt/__APPLE2ENH__/ - Target system is <tt/apple2enh/ +<item><tt/__ATARI2600__/ - Target system is <tt/atari2600/ <item><tt/__ATARI5200__/ - Target system is <tt/atari5200/ <item><tt/__ATARI__/ - Target system is <tt/atari/ or <tt/atarixl/ <item><tt/__ATARIXL__/ - Target system is <tt/atarixl/ @@ -4849,19 +4980,16 @@ including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: <enum> -<item> The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. -<item> Altered source versions must be plainly marked as such, and must not - be misrepresented as being the original software. -<item> This notice may not be removed or altered from any source - distribution. +<item> The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. +<item> Altered source versions must be plainly marked as such, and must not + be misrepresented as being the original software. +<item> This notice may not be removed or altered from any source + distribution. </enum> </article> - - -