-<!doctype linuxdoc system>
+<!doctype linuxdoc system> <!-- -*- text-mode -*- -->
<article>
<title>ca65 Users Guide
--help Help (this text)
--ignore-case Ignore case of symbols
--include-dir dir Set an include directory search path
+ --large-alignment Don't warn about large alignments
--listing name Create a listing file if assembly was ok
--list-bytes n Maximum number of bytes per listing line
--macpack-dir dir Set a macro package directory
never be generated in case of assembly errors.
+ <label id="option--large-alignment">
+ <tag><tt>--large-alignment</tt></tag>
+
+ Disable warnings about a large combined alignment. See the discussion of the
+ <tt><ref id=".ALIGN" name=".ALIGN"></tt> directive for futher information.
+
+
<label id="option--list-bytes">
<tag><tt>--list-bytes n</tt></tag>
operator. After doing
<tscreen><verb>
- two = 2
+ two = 2
</verb></tscreen>
may use the symbol "two" in every place where a number is expected, and it is
handled differently in a debugger:
<tscreen><verb>
- io := $d000
+ io := $d000
</verb></tscreen>
The right side can of course be an expression:
<tscreen><verb>
- four = two * two
+ four = two * two
+</verb></tscreen>
+
+
+<label id="variables">
+<sect1>Numeric variables<p>
+
+Within macros and other control structures (<tt><ref id=".REPEAT"
+name=".REPEAT"></tt>, ...) it is sometimes useful to have some sort of
+variable. This can be achieved by the <tt>.SET</tt> operator. It creates a
+symbol that may get assigned a different value later:
+
+<tscreen><verb>
+ four .set 4
+ lda #four ; Loads 4 into A
+ four .set 3
+ lda #four ; Loads 3 into A
+</verb></tscreen>
+
+Since the value of the symbol can change later, it must be possible to
+evaluate it when used (no delayed evaluation as with normal symbols). So the
+expression used as the value must be constant.
+
+Following is an example for a macro that generates a different label each time
+it is used. It uses the <tt><ref id=".SPRINTF" name=".SPRINTF"></tt> function
+and a numeric variable named <tt>lcount</tt>.
+
+<tscreen><verb>
+ .lcount .set 0 ; Initialize the counter
+
+ .macro genlab
+ .ident (.sprintf ("L%04X", lcount)):
+ lcount .set lcount + 1
+ .endmacro
</verb></tscreen>
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
+ 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!
+ bne @Loop ; ERROR: Unknown identifier!
</verb></tscreen>
<sect1>Unnamed labels<p>
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
<sect1>Using macros to define labels and constants<p>
-While there are drawbacks with this approach, it may be handy in some
-situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is
-possible to define symbols or constants that may be used elsewhere. Since
-the macro facility works on a very low level, there is no scoping. On the
-other side, you may also define string constants this way (this is not
+While there are drawbacks with this approach, it may be handy in a few rare
+situations. Using <tt><ref id=".DEFINE" name=".DEFINE"></tt>, it is possible
+to define symbols or constants that may be used elsewhere. One of the
+advantages is that you can use it to define string constants (this is not
possible with the other symbol types).
+Please note: <tt/.DEFINE/ style macros do token replacements on a low level,
+so the names do not adhere to scoping, diagnostics may be misleading, there
+are no symbols to look up in the map file, and there is no debug info.
+Especially the first problem in the list can lead to very nasty programming
+errors. Because of these problems, the general advice is, <bf/NOT/ do use
+<tt/.DEFINE/ if you don't have to.
+
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>
either a string or an expression.
+<sect1><tt>.BANK</tt><label id=".BANK"><p>
+
+ The <tt/.BANK/ function is used to support systems with banked memory. The
+ argument is an expression with exactly one segment reference - usually a
+ label. The function result is the value of the <tt/bank/ attribute assigned
+ to the run memory area of the segment. Please see the linker documentation
+ for more information about memory areas and their attributes.
+
+ The value of <tt/.BANK/ can be used to switch memory so that a memory bank
+ containing specific data is available.
+
+ The <tt/bank/ attribute is a 32 bit integer and so is the result of the
+ <tt/.BANK/ function. You will have to use <tt><ref id=".LOBYTE"
+ name=".LOBYTE"></tt> or similar functions to address just part of it.
+
+ Please note that <tt/.BANK/ will always get evaluated in the link stage, so
+ an expression containing <tt/.BANK/ can never be used where a constant known
+ result is expected (for example with <tt/.RES/).
+
+ Example:
+
+ <tscreen><verb>
+ .segment "BANK1"
+ .proc banked_func_1
+ ...
+ .endproc
+
+ .segment "BANK2"
+ .proc banked_func_2
+ ...
+ .endproc
+
+ .proc bank_table
+ .addr banked_func_1
+ .byte <.BANK (banked_func_1)
+
+ .addr banked_func_2
+ .byte <.BANK (banked_func_2)
+ .endproc
+ </verb></tscreen>
+
+
+
<sect1><tt>.BANKBYTE</tt><label id=".BANKBYTE"><p>
The function returns the bank byte (that is, bits 16-23) of its argument.
<sect1><tt>.ALIGN</tt><label id=".ALIGN"><p>
Align data to a given boundary. The command expects a constant integer
- argument that must be a power of two, plus an optional second argument
+ argument in the range 1 ... 65536, plus an optional second argument
in byte range. If there is a second argument, it is used as fill value,
otherwise the value defined in the linker configuration file is used
(the default for this value is zero).
- Since alignment depends on the base address of the module, you must
- give the same (or a greater) alignment for the segment when linking.
- The linker will give you a warning, if you don't do that.
+ <tt/.ALIGN/ will insert fill bytes, and the number of fill bytes depend of
+ the final address of the segment. <tt/.ALIGN/ cannot insert a variable
+ number of bytes, since that would break address calculations within the
+ module. So each <tt/.ALIGN/ expects the segment to be aligned to a multiple
+ of the alignment, because that allows the number of fill bytes to be
+ calculated in advance by the assembler. You are therefore required to
+ specify a matching alignment for the segment in the linker config. The
+ linker will output a warning if the alignment of the segment is less than
+ what is necessary to have a correct alignment in the object file.
Example:
.align 256
</verb></tscreen>
+ Some unexpected behaviour might occur if there are multiple <tt/.ALIGN/
+ commands with different arguments. To allow the assembler to calculate the
+ number of fill bytes in advance, the alignment of the segment must be a
+ multiple of each of the alignment factors. This may result in unexpectedly
+ large alignments for the segment within the module.
+
+ Example:
+
+ <tscreen><verb>
+ .align 15
+ .byte 15
+ .align 18
+ .byte 18
+ </verb></tscreen>
+
+ For the assembler to be able to align correctly, the segment must be aligned
+ to the least common multiple of 15 and 18 which is 90. The assembler will
+ calculate this automatically and will mark the segment with this value.
+
+ Unfortunately, the combined alignment may get rather large without the user
+ knowing about it, wasting space in the final executable. If we add another
+ alignment to the example above
+
+ <tscreen><verb>
+ .align 15
+ .byte 15
+ .align 18
+ .byte 18
+ .align 251
+ .byte 0
+ </verb></tscreen>
+
+ the assembler will force a segment alignment to the least common multiple of
+ 15, 18 and 251 - which is 22590. To protect the user against errors, the
+ assembler will issue a warning when the combined alignment exceeds 256. The
+ command line option <tt><ref id="option--large-alignment"
+ name="--large-alignment"></tt> will disable this warning.
+
+ Please note that with alignments that are a power of two (which were the
+ only alignments possible in older versions of the assembler), the problem is
+ less severe, because the least common multiple of powers to the same base is
+ always the larger one.
+
+
<sect1><tt>.ASCIIZ</tt><label id=".ASCIIZ"><p>
Start a define style macro definition. The command is followed by an
identifier (the macro name) and optionally by a list of formal arguments
in braces.
+
+ Please note that <tt/.DEFINE/ shares most disadvantages with its C
+ counterpart, so the general advice is, <bf/NOT/ do use <tt/.DEFINE/ if you
+ don't have to.
+
See also the <tt><ref id=".UNDEFINE" name=".UNDEFINE"></tt> command and
section <ref id="macros" name="Macros">.
and unions"">.
+<sect1><tt>.ENDUNION</tt><label id=".ENDUNION"><p>
+
+ Ends a union definition. See the <tt/<ref id=".UNION" name=".UNION">/
+ command and the separate section named <ref id="structs" name=""Structs
+ and unions"">.
+
+
<sect1><tt>.ENUM</tt><label id=".ENUM"><p>
Start an enumeration. This directive is very similar to the C <tt/enum/
at character is not allowed to start an identifier, even with this
feature enabled.
- <tag><tt>c_comments</tt></tag>
+ <tag><tt>c_comments</tt><label id="c_comments"></tag>
Allow C like comments using <tt>/*</tt> and <tt>*/</tt> as left and right
comment terminators. Note that C comments may not be nested. There's also a
dollar character is not allowed to start an identifier, even with this
feature enabled.
- <tag><tt>dollar_is_pc</tt></tag>
+ <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
gives the value of the current PC in expressions.
Note: Assignment to the pseudo variable is not allowed.
- <tag><tt>labels_without_colons</tt></tag>
+ <tag><tt>force_range</tt><label id="force_range"></tag>
+
+ Force expressions into their valid range for immediate addressing and
+ storage operators like <tt><ref id=".BYTE" name=".BYTE"></tt> and
+ <tt><ref id=".WORD" name=".WORD"></tt>. Be very careful with this one,
+ since it will completely disable error checks.
+
+ <tag><tt>labels_without_colons</tt><label id="labels_without_colons"></tag>
Allow labels without a trailing colon. These labels are only accepted,
if they start at the beginning of a line (no leading white space).
overridden. When using this feature, you may also get into trouble if
later versions of the assembler define new keywords starting with a dot.
- <tag><tt>loose_char_term</tt></tag>
+ <tag><tt>loose_char_term</tt><label id="loose_char_term"></tag>
Accept single quotes as well as double quotes as terminators for char
constants.
- <tag><tt>loose_string_term</tt></tag>
+ <tag><tt>loose_string_term</tt><label id="loose_string_term"></tag>
Accept single quotes as well as double quotes as terminators for string
constants.
- <tag><tt>missing_char_term</tt></tag>
+ <tag><tt>missing_char_term</tt><label id="missing_char_term"></tag>
Accept single quoted character constants where the terminating quote is
missing.
effect will only enable absolute mode for the current segment. Dito for
<tt><ref id=".RELOC" name=".RELOC"></tt>.
- <tag><tt>pc_assignment</tt></tag>
+ <tag><tt>pc_assignment</tt><label id="pc_assignment"></tag>
Allow assignments to the PC symbol (`*' or `$' if <tt/dollar_is_pc/
is enabled). Such an assignment is handled identical to the <tt><ref
removing the lines with the assignments may also be an option when porting
code written for older assemblers).
- <tag><tt>ubiquitous_idents</tt></tag>
+ <tag><tt>ubiquitous_idents</tt><label id="ubiquitous_idents"></tag>
Allow the use of instructions names as names for macros and symbols. This
makes it possible to "overload" instructions by defining a macro with the
<sect1><tt>.MACPACK</tt><label id=".MACPACK"><p>
-
+
Insert a predefined macro package. The command is followed by an
identifier specifying the macro package to insert. Available macro
packages are:
id=".RODATA" name=".RODATA"></tt>
+<sect1><tt>.SET</tt><label id=".SET"><p>
+
+ <tt/.SET/ is used to assign a value to a variable. See <ref id="variables"
+ name="Numeric variables"> for a full description.
+
+
<sect1><tt>.SETCPU</tt><label id=".SETCPU"><p>
Switch the CPU instruction set. The command is followed by a string that
Starts a struct definition. Structs are covered in a separate section named
<ref id="structs" name=""Structs and unions"">.
- See: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>
+ See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>,
+ <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>,
+ <tt><ref id=".UNION" name=".UNION"></tt>
<sect1><tt>.SUNPLUS</tt><label id=".SUNPLUS"><p>
section <ref id="macros" name="Macros">.
+<sect1><tt>.UNION</tt><label id=".UNION"><p>
+
+ Starts a union definition. Unions are covered in a separate section named
+ <ref id="structs" name=""Structs and unions"">.
+
+ See also: <tt><ref id=".ENDSTRUCT" name=".ENDSTRUCT"></tt>,
+ <tt><ref id=".ENDUNION" name=".ENDUNION"></tt>,
+ <tt><ref id=".STRUCT" name=".STRUCT"></tt>
+
+
<sect1><tt>.WARNING</tt><label id=".WARNING"><p>
Force an assembly warning. The assembler will output a warning message
.endmacro
</verb></tscreen>
- See also: <tt><ref id=".ERROR" name=".ERROR"></tt>
+ See also: <tt><ref id=".ERROR" name=".ERROR"></tt>,
<tt><ref id=".FATAL" name=".FATAL"></tt>,
<tt><ref id=".OUT" name=".OUT"></tt>
</verb></tscreen>
A union shares the total space between all its members, its size is the same
-as that of the largest member.
+as that of the largest member. The offset of all members relative to the union
+is zero.
+
+<tscreen><verb>
+ .union Entry
+ index .word
+ ptr .addr
+ .endunion
+</verb></tscreen>
A struct or union must not necessarily have a name. If it is anonymous, no
local scope is opened, the identifiers used to name the members are placed
projects / cc65 / blobdiff