diff --git a/doc/ca65.sgml b/doc/ca65.sgml index 67c7d9f66..3d7324ed1 100644 --- a/doc/ca65.sgml +++ b/doc/ca65.sgml @@ -440,24 +440,10 @@ Available operators sorted by precedence: Op Description Precedence ------------------------------------------------------------------- - .CONCAT Builtin function 0 - .LEFT Builtin function 0 - .MID Builtin function 0 - .RIGHT Builtin function 0 - .STRING Builtin function 0 + Builtin string functions 0 - * Builtin pseudo variable (r/o) 1 - .BLANK Builtin function 1 - .CONST Builtin function 1 - .CPU Builtin pseudo variable (r/o) 1 - .DEFINED Builtin function 1 - .MATCH Builtin function 1 - .TCOUNT Builtin function 1 - .TIME Builtin function 1 - .VERSION Builtin function 1 - .XMATCH Builtin function 1 - .PARAMCOUNT Builtin pseudo variable (r/o) 1 - .REFERENCED Builtin function 1 + Builtin pseudo variables 1 + Builtin pseudo functions 1 + Unary plus 1 - Unary minus 1 ~ Unary bitwise not 1 @@ -504,15 +490,6 @@ Available operators sorted by precedence: To force a specific order of evaluation, braces may be used as usual. -Some of the pseudo variables mentioned above need some more explanation: - - - * This symbol is replaced by the value of the program - counter at start of the current instruction. Note, that - '*' yields a rvalue, that means, you cannot assign to it. - Use .ORG to set the program counter in sections with - absolute code. -

@@ -936,12 +913,536 @@ if you want to access the "other" symbol Pseudo variables

+ +Pseudo variables are readable in all cases, and in some special cases also +writable. + +*

+ + Reading this pseudo variable will return the program counter at the start + of the current input line. + + Assignment to this variable is possible when / is used. Note: You should not use + assignments to / instead. + + +.CPU

+ + Reading this pseudo variable will give a constant integer value that + tells which CPU is currently enabled. It can also tell which instruction + set the CPU is able to translate. The value read from the pseudo variable + should be further examined by using one of the constants defined by the + "cpu" macro package (see /). + + It may be used to replace the .IFPxx pseudo instructions or to construct + even more complex expressions. + + Example: + + + .macpack cpu + .if (.cpu .bitand CPU_ISET_65816) + phx + phy + .else + txa + pha + tya + pha + .endif + + + +.PARAMCOUNT

+ + This builtin pseudo variable is only available in macros. It is replaced by + the actual number of parameters that were given in the macro invocation. + + Example: + + + .macro foo arg1, arg2, arg3 + .if .paramcount <> 3 + .error "Too few parameters for macro foo" + .endif + ... + .endmacro + + + See section . + + +.TIME

+ + Reading this pseudo variable will give a constant integer value that + represents the current time in POSIX standard (as seconds since the + Epoch). + + It may be used to encode the time of translation somewhere in the created + code. + + Example: + + + .dword .time ; Place time here + + + +.VERSION

+ + Reading this pseudo variable will give the assembler version according to + the following formula: + + VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH + + It may be used to encode the assembler version or check the assembler for + special features not available with older versions. + + Example: + + Version 2.11.1 of the assembler will return $2B1 as numerical constant when + reading the pseudo variable Control commands

+ +Pseudo functions expect their arguments in parenthesis, and they have a result, +either a string or an expression. + + +.BANKBYTE

+ + The function returns the bank byte (that is, bits 16-23) of its argument. + It works identical to the '^' operator. + + See: , + + + +.BLANK

+ + Builtin function. The function evaluates its argument in braces and + yields "false" if the argument is non blank (there is an argument), and + "true" if there is no argument. As an example, the + .if .blank(arg) + + + +.CONCAT

+ + Builtin string function. The function allows to concatenate a list of string + constants separated by commas. The result is a string constant that is the + concatentation of all arguments. This function is most useful in macros and + when used together with the + .include .concat ("myheader", ".", "inc") + + + This is the same as the command + + + .include "myheader.inc" + + + +.CONST

+ + Builtin function. The function evaluates its argument in braces and + yields "true" if the argument is a constant expression (that is, an + expression that yields a constant value at assembly time) and "false" + otherwise. As an example, the .IFCONST statement may be replaced by + + + .if .const(a + 3) + + + +.HIBYTE

+ + The function returns the high byte (that is, bits 8-15) of its argument. + It works identical to the '>' operator. + + See: , + + + +.HIWORD

+ + The function returns the high word (that is, bits 16-31) of its argument. + + See: + + +.LEFT

+ + Builtin function. Extracts the left part of a given token list. + + Syntax: + + + .LEFT (<int expr>, <token list>) + + + The first integer expression gives the number of tokens to extract from + the token list. The second argument is the token list itself. + + Example: + + To check in a macro if the given argument has a '#' as first token + (immidiate addressing mode), use something like this: + + + .macro ldax arg + ... + .if (.match (.left (1, arg), #)) + + ; ldax called with immidiate operand + ... + + .endif + ... + .endmacro + + + See also the and builtin functions. + + +.LOBYTE

+ + The function returns the low byte (that is, bits 0-7) of its argument. + It works identical to the '<' operator. + + See: , + + + +.LOWORD

+ + The function returns the low word (that is, bits 0-15) of its argument. + + See: + + +.MATCH

+ + Builtin function. Matches two token lists against each other. This is + most useful within macros, since macros are not stored as strings, but + as lists of tokens. + + The syntax is + + + .MATCH(<token list #1>, <token list #2>) + + + Both token list may contain arbitrary tokens with the exception of the + terminator token (comma resp. right parenthesis) and + + + end-of-line + end-of-file + + + Often a macro parameter is used for any of the token lists. + + Please note that the function does only compare tokens, not token + attributes. So any number is equal to any other number, regardless of the + actual value. The same is true for strings. If you need to compare tokens + function. + + Example: + + Assume the macro function + to check for this and print and error for invalid calls. + + + .macro asr arg + + .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 + + .endmacro + + + The macro will only accept no arguments, or one argument that must be the + reserved keyword "A". + + See: + + +.MID

+ + Builtin function. Takes a starting index, a count and a token list as + arguments. Will return part of the token list. + + Syntax: + + + .MID (<int expr>, <int expr>, <token list>) + + + The first integer expression gives the starting token in the list (the + first token has index 0). The second integer expression gives the number + of tokens to extract from the token list. The third argument is the + token list itself. + + Example: + + To check in a macro if the given argument has a ' + .macro ldax arg + ... + .if (.match (.mid (0, 1, arg), #)) + + ; ldax called with immidiate operand + ... + + .endif + ... + .endmacro + + + See also the and builtin functions. + + +.REF, .REFERENCED

+ + Builtin function. The function expects an identifier as argument in braces. + The argument is evaluated, and the function yields "true" if the identifier + is a symbol that has already been referenced somewhere in the source file up + to the current position. Otherwise the function yields false. As an example, + the statement may be replaced by + + + .if .referenced(a) + + + See: + + +.RIGHT

+ + Builtin function. Extracts the right part of a given token list. + + Syntax: + + + .RIGHT (<int expr>, <token list>) + + + The first integer expression gives the number of tokens to extract from + the token list. The second argument is the token list itself. + + See also the and builtin functions. + + +.SIZEOF

+ + + .struct Point ; Struct size = 4 + xcoord .word + xcoord .word + .endstruct + + P: .tag Point ; Declare a point + @P: .tag Point ; Declare another point + + .code + .proc Code + nop + .proc Inner + nop + .endproc + nop + .endproc + + .proc Data + .data ; Segment switch!!! + .res 4 + .endproc + + + + + will have the value 4, because this is the size of struct + will have the value 2, because this is the size of the member + will have the value 4, this is the size of the data declared on the same + source line as the label + will have the value 4, see above. The example demonstrates that + will have the value 3, since this is amount of data emitted into the code + segment, the segment that was active when + will have the value 1 as expected. + + + will have the value 0. Data is emitted within the scope + + +.STRAT

+ + Builtin function. The function accepts a string and an index as + arguments and returns the value of the character at the given position + as an integer value. The index is zero based. + + Example: + + + .macro M Arg + ; Check if the argument string starts with '#' + .if (.strat (Arg, 0) = '#') + ... + .endif + .endmacro + + + +.STRING

+ + Builtin function. The function accepts an argument in braces and converts + this argument into a string constant. The argument may be an identifier, or + a constant numeric value. + + Since you can use a string in the first place, the use of the function may + not be obvious. However, it is useful in macros, or more complex setups. + + Example: + + + ; Emulate other assemblers: + .macro section name + .segment .string(name) + .endmacro + + + +.STRLEN

+ + Builtin function. The function accepts a string argument in braces and + eveluates to the length of the string. + + Example: + + The following macro encodes a string as a pascal style string with + a leading length byte. + + + .macro PString Arg + .byte .strlen(Arg), Arg + .endmacro + + + +.TCOUNT

+ + Builtin function. The function accepts a token list in braces. The + function result is the number of tokens given as argument. + + Example: + + The + .macro ldax arg + .if (.match (.mid (0, 1, arg), #)) + ; ldax called with immidiate operand + lda #<(.right (.tcount (arg)-1, arg)) + ldx #>(.right (.tcount (arg)-1, arg)) + .else + ... + .endif + .endmacro + + + +.XMATCH

+ + Builtin function. Matches two token lists against each other. This is + most useful within macros, since macros are not stored as strings, but + as lists of tokens. + + The syntax is + + + .XMATCH(<token list #1>, <token list #2>) + + + Both token list may contain arbitrary tokens with the exception of the + terminator token (comma resp. right parenthesis) and + + + end-of-line + end-of-file + + + Often a macro parameter is used for any of the token lists. + + The function compares tokens function. + + See: + + + +Control commands

-

Here's a list of all control commands and a description, what they do: @@ -1064,18 +1565,6 @@ Here's a list of all control commands and a description, what they do: -.BLANK

- - Builtin function. The function evaluates its argument in braces and - yields "false" if the argument is non blank (there is an argument), and - "true" if there is no argument. As an example, the - .if .blank(arg) - - - .BSS

Switch to the BSS segment. The name of the BSS segment is always "BSS", @@ -1183,40 +1672,6 @@ Here's a list of all control commands and a description, what they do: feature in more detail. -.CONCAT

- - Builtin function. The function allows to concatenate a list of string - constants separated by commas. The result is a string constant that - is the concatentation of all arguments. This function is most useful - in macros and when used together with the - .include .concat ("myheader", ".", "inc") - - - This is the same as the command - - - .include "myheader.inc" - - - -.CONST

- - Builtin function. The function evaluates its argument in braces and - yields "true" if the argument is a constant expression (that is, an - expression that yields a constant value at assembly time) and "false" - otherwise. As an example, the .IFCONST statement may be replaced by - - - .if .const(a + 3) - - - .CONSTRUCTOR

Export a symbol and mark it as a module constructor. This may be used @@ -1248,33 +1703,6 @@ Here's a list of all control commands and a description, what they do: feature in more detail. -.CPU

- - Reading this pseudo variable will give a constant integer value that - tells which CPU is currently enabled. It can also tell which instruction - set the CPU is able to translate. The value read from the pseudo variable - should be further examined by using one of the constants defined by the - "cpu" macro package (see /). - - It may be used to replace the .IFPxx pseudo instructions or to construct - even more complex expressions. - - Example: - - - .macpack cpu - .if (.cpu .bitand CPU_ISET_65816) - phx - phy - .else - txa - pha - tya - pha - .endif - - - .DATA

Switch to the DATA segment. The name of the DATA segment is always @@ -1436,8 +1864,9 @@ Here's a list of all control commands and a description, what they do: .ENDSTRUCT

- Ends a struct definition. See the section named . + Ends a struct definition. See the / + command and the separate section named . .ENUM

@@ -1973,41 +2402,6 @@ Here's a list of all control commands and a description, what they do: -.LEFT

- - Builtin function. Extracts the left part of a given token list. - - Syntax: - - - .LEFT (<int expr>, <token list>) - - - The first integer expression gives the number of tokens to extract from - the token list. The second argument is the token list itself. - - Example: - - To check in a macro if the given argument has a '#' as first token - (immidiate addressing mode), use something like this: - - - .macro ldax arg - ... - .if (.match (.left (1, arg), #)) - - ; ldax called with immidiate operand - ... - - .endif - ... - .endmacro - - - See also the and builtin functions. - - .LINECONT

Switch on or off line continuations using the backslash character @@ -2146,99 +2540,6 @@ Here's a list of all control commands and a description, what they do: See section . -.MATCH

- - Builtin function. Matches two token lists against each other. This is - most useful within macros, since macros are not stored as strings, but - as lists of tokens. - - The syntax is - - - .MATCH(<token list #1>, <token list #2>) - - - Both token list may contain arbitrary tokens with the exception of the - terminator token (comma resp. right parenthesis) and - - - end-of-line - end-of-file - - - Often a macro parameter is used for any of the token lists. - - Please note that the function does only compare tokens, not token - attributes. So any number is equal to any other number, regardless of the - actual value. The same is true for strings. If you need to compare tokens - function. - - Example: - - Assume the macro function - to check for this and print and error for invalid calls. - - - .macro asr arg - - .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 - - .endmacro - - - The macro will only accept no arguments, or one argument that must be the - reserved keyword "A". - - See: - - -.MID

- - Builtin function. Takes a starting index, a count and a token list as - arguments. Will return part of the token list. - - Syntax: - - - .MID (<int expr>, <int expr>, <token list>) - - - The first integer expression gives the starting token in the list (the - first token has index 0). The second integer expression gives the number - of tokens to extract from the token list. The third argument is the - token list itself. - - Example: - - To check in a macro if the given argument has a ' - .macro ldax arg - ... - .if (.match (.mid (0, 1, arg), #)) - - ; ldax called with immidiate operand - ... - - .endif - ... - .endmacro - - - See also the and builtin functions. - - .ORG

Start a section of absolute code. The command is followed by a constant @@ -2313,25 +2614,6 @@ Here's a list of all control commands and a description, what they do: -.PARAMCOUNT

- - This builtin pseudo variable is only available in macros. It is replaced by - the actual number of parameters that were given in the macro invocation. - - Example: - - - .macro foo arg1, arg2, arg3 - .if .paramcount <> 3 - .error "Too few parameters for macro foo" - .endif - ... - .endmacro - - - See section . - - .PC02

Enable the 65C02 instructions set. This instruction set includes all @@ -2415,21 +2697,6 @@ Here's a list of all control commands and a description, what they do: See: -.REF, .REFERENCED

- - Builtin function. The function expects an identifier as argument in braces. - The argument is evaluated, and the function yields "true" if the identifier - is a symbol that has already been referenced somewhere in the source file up - to the current position. Otherwise the function yields false. As an example, - the statement may be replaced by - - - .if .referenced(a) - - - See: - - .REPEAT

Repeat all commands between -.RIGHT

- - Builtin function. Extracts the right part of a given token list. - - Syntax: - - - .RIGHT (<int expr>, <token list>) - - - The first integer expression gives the number of tokens to extract from - the token list. The second argument is the token list itself. - - See also the and builtin functions. - - .RODATA

Switch to the RODATA segment. The name of the RODATA segment is always @@ -2610,80 +2860,6 @@ Here's a list of all control commands and a description, what they do: -.SIZEOF

- - - .struct Point ; Struct size = 4 - xcoord .word - xcoord .word - .endstruct - - P: .tag Point ; Declare a point - @P: .tag Point ; Declare another point - - .code - .proc Code - nop - .proc Inner - nop - .endproc - nop - .endproc - - .proc Data - .data ; Segment switch!!! - .res 4 - .endproc - - - - - will have the value 4, because this is the size of struct - will have the value 2, because this is the size of the member - will have the value 4, this is the size of the data declared on the same - source line as the label - will have the value 4, see above. The example demonstrates that - will have the value 3, since this is amount of data emitted into the code - segment, the segment that was active when - will have the value 1 as expected. - - - will have the value 0. Data is emitted within the scope - - .SMART

Switch on or off smart mode. The command must be followed by a '+' or @@ -2720,64 +2896,12 @@ Here's a list of all control commands and a description, what they do: -.STRAT

- - Builtin function. The function accepts a string and an index as - arguments and returns the value of the character at the given position - as an integer value. The index is zero based. - - Example: - - - .macro M Arg - ; Check if the argument string starts with '#' - .if (.strat (Arg, 0) = '#') - ... - .endif - .endmacro - - - -.STRING

- - Builtin function. The function accepts an argument in braces and converts - this argument into a string constant. The argument may be an identifier, or - a constant numeric value. - - Since you can use a string in the first place, the use of the function may - not be obvious. However, it is useful in macros, or more complex setups. - - Example: - - - ; Emulate other assemblers: - .macro section name - .segment .string(name) - .endmacro - - - -.STRLEN

- - Builtin function. The function accepts a string argument in braces and - eveluates to the length of the string. - - Example: - - The following macro encodes a string as a pascal style string with - a leading length byte. - - - .macro PString Arg - .byte .strlen(Arg), Arg - .endmacro - - - .STRUCT

- Starts a struct definition. See the section named . + Starts a struct definition. Structs are covered in a separate section named + . + + See: .SUNPLUS

@@ -2808,62 +2932,6 @@ Here's a list of all control commands and a description, what they do: -.TCOUNT

- - Builtin function. The function accepts a token list in braces. The - function result is the number of tokens given as argument. - - Example: - - The - .macro ldax arg - .if (.match (.mid (0, 1, arg), #)) - ; ldax called with immidiate operand - lda #<(.right (.tcount (arg)-1, arg)) - ldx #>(.right (.tcount (arg)-1, arg)) - .else - ... - .endif - .endmacro - - - -.TIME

- - Reading this pseudo variable will give a constant integer value that - represents the current time in POSIX standard (as seconds since the - Epoch). - - It may be used to encode the time of translation somewhere in the created - code. - - Example: - - - .dword .time ; Place time here - - - -.VERSION

- - Reading this pseudo variable will give the assembler version according to - the following formula: - - VER_MAJOR*$100 + VER_MINOR*$10 + VER_PATCH - - It may be used to encode the assembler version or check the assembler for - special features not available with older versions. - - Example: - - Version 2.11.1 of the assembler will return $2B1 as numerical constant when - reading the pseudo variable .WARNING

Force an assembly warning. The assembler will output a warning message @@ -2906,35 +2974,6 @@ Here's a list of all control commands and a description, what they do: -.XMATCH

- - Builtin function. Matches two token lists against each other. This is - most useful within macros, since macros are not stored as strings, but - as lists of tokens. - - The syntax is - - - .XMATCH(<token list #1>, <token list #2>) - - - Both token list may contain arbitrary tokens with the exception of the - terminator token (comma resp. right parenthesis) and - - - end-of-line - end-of-file - - - Often a macro parameter is used for any of the token lists. - - The function compares tokens function. - - See: - - .ZEROPAGE

Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment. @@ -3445,7 +3484,7 @@ CPUs (the latter two are upwards compatible to the 65SC02). Structs and unions are special forms of . They are to some degree comparable to their C counterparts. Both have a list of members. Each member allocates storage and may optionally have a name, which, -in case of a struct, is the offset from the beginning and, in case of a union +in case of a struct, is the offset from the beginning and, in case of a union, is always zero. Here is an example for a very simple struct with two members and a total size @@ -3488,13 +3527,26 @@ already defined structs or unions in structs: .struct Circle Origin .tag Point - Radius .word + Radius .byte .endstruct Space for a struct or union may be allocated using the directive. + + C: .tag Circle + + +Currently, members are just offsets from the start of the struct or union. To +access a field of a struct, the member offset has to be added to the address +of the struct itself: + + + lda C+Circle::Radius ; Load circle radius into A + + +This may change in a future version of the assembler. Module constructors/destructors