223cc6685e
git-svn-id: svn://svn.compuextreme.de/Viitor/V963/Viitor_cc65@5933 504e572c-2e33-0410-9681-be2bf7408885
1997 lines
63 KiB
HTML
1997 lines
63 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.20">
|
|
<TITLE>ca65 Users Guide: Control commands</TITLE>
|
|
<LINK HREF="ca65-11.html" REL=next>
|
|
<LINK HREF="ca65-9.html" REL=previous>
|
|
<LINK HREF="ca65.html#toc10" REL=contents>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="ca65-11.html">Next</A>
|
|
<A HREF="ca65-9.html">Previous</A>
|
|
<A HREF="ca65.html#toc10">Contents</A>
|
|
<HR>
|
|
<H2><A NAME="control-commands"></A> <A NAME="s10">10.</A> <A HREF="ca65.html#toc10">Control commands</A></H2>
|
|
|
|
|
|
<P>Here's a list of all control commands and a description, what they do:</P>
|
|
|
|
|
|
<H2><A NAME=".A16"></A> <A NAME="ss10.1">10.1</A> <A HREF="ca65.html#toc10.1"><CODE>.A16</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Valid only in 65816 mode. Switch the accumulator to 16 bit.</P>
|
|
<P>Note: This command will not emit any code, it will tell the assembler to
|
|
create 16 bit operands for immediate accumulator addressing mode.</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="#.SMART">.SMART</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".A8"></A> <A NAME="ss10.2">10.2</A> <A HREF="ca65.html#toc10.2"><CODE>.A8</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Valid only in 65816 mode. Switch the accumulator to 8 bit.</P>
|
|
<P>Note: This command will not emit any code, it will tell the assembler to
|
|
create 8 bit operands for immediate accu addressing mode.</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="#.SMART">.SMART</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".ADDR"></A> <A NAME="ss10.3">10.3</A> <A HREF="ca65.html#toc10.3"><CODE>.ADDR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define word sized data. In 6502 mode, this is an alias for <CODE>.WORD</CODE> and
|
|
may be used for better readability if the data words are address values. In
|
|
65816 mode, the address is forced to be 16 bit wide to fit into the current
|
|
segment. See also <CODE>
|
|
<A HREF="#.FARADDR">.FARADDR</A></CODE>. The command
|
|
must be followed by a sequence of (not necessarily constant) expressions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.addr $0D00, $AF13, _Clear
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.FARADDR">.FARADDR</A></CODE>, <CODE>
|
|
<A HREF="#.WORD">.WORD</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".ALIGN"></A> <A NAME="ss10.4">10.4</A> <A HREF="ca65.html#toc10.4"><CODE>.ALIGN</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<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
|
|
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).</P>
|
|
<P>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.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.align 256
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".ASCIIZ"></A> <A NAME="ss10.5">10.5</A> <A HREF="ca65.html#toc10.5"><CODE>.ASCIIZ</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define a string with a trailing zero.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Msg: .asciiz "Hello world"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>This will put the string "Hello world" followed by a binary zero into
|
|
the current segment. There may be more strings separated by commas, but
|
|
the binary zero is only appended once (after the last one).</P>
|
|
|
|
|
|
<H2><A NAME=".ASSERT"></A> <A NAME="ss10.6">10.6</A> <A HREF="ca65.html#toc10.6"><CODE>.ASSERT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Add an assertion. The command is followed by an expression, an action
|
|
specifier, and an optional message that is output in case the assertion
|
|
fails. If no message was given, the string "Assertion failed" is used. The
|
|
action specifier may be one of <CODE>warning</CODE> or <CODE>error</CODE>. The assertion is
|
|
evaluated by the assembler if possible, and also passed to the linker in the
|
|
object file (if one is generated). The linker will then evaluate the
|
|
expression when segment placement has been done.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.assert * = $8000, error, "Code not at $8000"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>The example assertion will check that the current location is at $8000,
|
|
when the output file is written, and abort with an error if this is not
|
|
the case. More complex expressions are possible. The action specifier
|
|
<CODE>warning</CODE> outputs a warning, while the <CODE>error</CODE> specifier outputs
|
|
an error message. In the latter case, generation if the output file is
|
|
suppressed in both the assembler and linker.</P>
|
|
|
|
|
|
<H2><A NAME=".AUTOIMPORT"></A> <A NAME="ss10.7">10.7</A> <A HREF="ca65.html#toc10.7"><CODE>.AUTOIMPORT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Is followed by a plus or a minus character. When switched on (using a
|
|
+), undefined symbols are automatically marked as import instead of
|
|
giving errors. When switched off (which is the default so this does not
|
|
make much sense), this does not happen and an error message is
|
|
displayed. The state of the autoimport flag is evaluated when the
|
|
complete source was translated, before outputting actual code, so it is
|
|
<EM>not</EM> possible to switch this feature on or off for separate sections
|
|
of code. The last setting is used for all symbols.</P>
|
|
<P>You should probably not use this switch because it delays error
|
|
messages about undefined symbols until the link stage. The cc65
|
|
compiler (which is supposed to produce correct assembler code in all
|
|
circumstances, something which is not true for most assembler
|
|
programmers) will insert this command to avoid importing each and every
|
|
routine from the runtime library.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.autoimport + ; Switch on auto import
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".BSS"></A> <A NAME="ss10.8">10.8</A> <A HREF="ca65.html#toc10.8"><CODE>.BSS</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch to the BSS segment. The name of the BSS segment is always "BSS",
|
|
so this is a shortcut for</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.segment "BSS"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.SEGMENT">.SEGMENT</A></CODE> command.</P>
|
|
|
|
|
|
<H2><A NAME=".BYTE"></A> <A NAME="ss10.9">10.9</A> <A HREF="ca65.html#toc10.9"><CODE>.BYT, .BYTE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define byte sized data. Must be followed by a sequence of (byte ranged)
|
|
expressions or strings.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.byte "Hello "
|
|
.byt "world", $0D, $00
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".CASE"></A> <A NAME="ss10.10">10.10</A> <A HREF="ca65.html#toc10.10"><CODE>.CASE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch on or off case sensitivity on identifiers. The default is off
|
|
(that is, identifiers are case sensitive), but may be changed by the
|
|
-i switch on the command line.
|
|
The command must be followed by a '+' or '-' character to switch the
|
|
option on or off respectively.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.case - ; Identifiers are not case sensitive
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".CHARMAP"></A> <A NAME="ss10.11">10.11</A> <A HREF="ca65.html#toc10.11"><CODE>.CHARMAP</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Apply a custom mapping for characters. The command is followed by two
|
|
numbers in the range 1..255. The first one is the index of the source
|
|
character, the second one is the mapping. The mapping applies to all
|
|
character and string constants when they generate output, and overrides
|
|
a mapping table specified with the <CODE>
|
|
<A HREF="ca65-2.html#option-t">-t</A></CODE>
|
|
command line switch.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.charmap $41, $61 ; Map 'A' to 'a'
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".CODE"></A> <A NAME="ss10.12">10.12</A> <A HREF="ca65.html#toc10.12"><CODE>.CODE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch to the CODE segment. The name of the CODE segment is always
|
|
"CODE", so this is a shortcut for</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.segment "CODE"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.SEGMENT">.SEGMENT</A></CODE> command.</P>
|
|
|
|
|
|
<H2><A NAME=".CONDES"></A> <A NAME="ss10.13">10.13</A> <A HREF="ca65.html#toc10.13"><CODE>.CONDES</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Export a symbol and mark it in a special way. The linker is able to build
|
|
tables of all such symbols. This may be used to automatically create a list
|
|
of functions needed to initialize linked library modules.</P>
|
|
<P>Note: The linker has a feature to build a table of marked routines, but it
|
|
is your code that must call these routines, so just declaring a symbol with
|
|
<CODE>.CONDES</CODE> does nothing by itself.</P>
|
|
<P>All symbols are exported as an absolute (16 bit) symbol. You don't need to
|
|
use an additional <CODE>
|
|
<A HREF="#.EXPORT">.EXPORT</A></CODE> statement, this
|
|
is implied by <CODE>.CONDES</CODE>.</P>
|
|
<P><CODE>.CONDES</CODE> is followed by the type, which may be <CODE>constructor</CODE>,
|
|
<CODE>destructor</CODE> or a numeric value between 0 and 6 (where 0 is the same as
|
|
specifying <CODE>constructor</CODE> and 1 is equal to specifying <CODE>destructor</CODE>).
|
|
The <CODE>
|
|
<A HREF="#.CONSTRUCTOR">.CONSTRUCTOR</A></CODE>, <CODE>
|
|
<A HREF="#.DESTRUCTOR">.DESTRUCTOR</A></CODE> and <CODE>
|
|
<A HREF="#.INTERRUPTOR">.INTERRUPTOR</A></CODE> commands are actually shortcuts for <CODE>.CONDES</CODE>
|
|
with a type of <CODE>constructor</CODE> resp. <CODE>destructor</CODE> or <CODE>interruptor</CODE>.</P>
|
|
<P>After the type, an optional priority may be specified. Higher numeric values
|
|
mean higher priority. If no priority is given, the default priority of 7 is
|
|
used. Be careful when assigning priorities to your own module constructors
|
|
so they won't interfere with the ones in the cc65 library.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.condes ModuleInit, constructor
|
|
.condes ModInit, 0, 16
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See the <CODE>
|
|
<A HREF="#.CONSTRUCTOR">.CONSTRUCTOR</A></CODE>, <CODE>
|
|
<A HREF="#.DESTRUCTOR">.DESTRUCTOR</A></CODE> and <CODE>
|
|
<A HREF="#.INTERRUPTOR">.INTERRUPTOR</A></CODE> commands and the separate section
|
|
<A HREF="ca65-15.html#condes">Module constructors/destructors</A> explaining the feature in more
|
|
detail.</P>
|
|
|
|
|
|
<H2><A NAME=".CONSTRUCTOR"></A> <A NAME="ss10.14">10.14</A> <A HREF="ca65.html#toc10.14"><CODE>.CONSTRUCTOR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Export a symbol and mark it as a module constructor. This may be used
|
|
together with the linker to build a table of constructor subroutines that
|
|
are called by the startup code.</P>
|
|
<P>Note: The linker has a feature to build a table of marked routines, but it
|
|
is your code that must call these routines, so just declaring a symbol as
|
|
constructor does nothing by itself.</P>
|
|
<P>A constructor is always exported as an absolute (16 bit) symbol. You don't
|
|
need to use an additional <CODE>.export</CODE> statement, this is implied by
|
|
<CODE>.constructor</CODE>. It may have an optional priority that is separated by a
|
|
comma. Higher numeric values mean a higher priority. If no priority is
|
|
given, the default priority of 7 is used. Be careful when assigning
|
|
priorities to your own module constructors so they won't interfere with the
|
|
ones in the cc65 library.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.constructor ModuleInit
|
|
.constructor ModInit, 16
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See the <CODE>
|
|
<A HREF="#.CONDES">.CONDES</A></CODE> and <CODE>
|
|
<A HREF="#.DESTRUCTOR">.DESTRUCTOR</A></CODE> commands and the separate section
|
|
<A HREF="ca65-15.html#condes">Module constructors/destructors</A> explaining the
|
|
feature in more detail.</P>
|
|
|
|
|
|
<H2><A NAME=".DATA"></A> <A NAME="ss10.15">10.15</A> <A HREF="ca65.html#toc10.15"><CODE>.DATA</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch to the DATA segment. The name of the DATA segment is always
|
|
"DATA", so this is a shortcut for</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.segment "DATA"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.SEGMENT">.SEGMENT</A></CODE> command.</P>
|
|
|
|
|
|
<H2><A NAME=".DBYT"></A> <A NAME="ss10.16">10.16</A> <A HREF="ca65.html#toc10.16"><CODE>.DBYT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define word sized data with the hi and lo bytes swapped (use <CODE>.WORD</CODE> to
|
|
create word sized data in native 65XX format). Must be followed by a
|
|
sequence of (word ranged) expressions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.dbyt $1234, $4512
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>This will emit the bytes</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
$12 $34 $45 $12
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>into the current segment in that order.</P>
|
|
|
|
|
|
<H2><A NAME=".DEBUGINFO"></A> <A NAME="ss10.17">10.17</A> <A HREF="ca65.html#toc10.17"><CODE>.DEBUGINFO</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch on or off debug info generation. The default is off (that is,
|
|
the object file will not contain debug infos), but may be changed by the
|
|
-g switch on the command line.
|
|
The command must be followed by a '+' or '-' character to switch the
|
|
option on or off respectively.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.debuginfo + ; Generate debug info
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".DEFINE"></A> <A NAME="ss10.18">10.18</A> <A HREF="ca65.html#toc10.18"><CODE>.DEFINE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<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.
|
|
See section
|
|
<A HREF="ca65-11.html#macros">Macros</A>.</P>
|
|
|
|
|
|
<H2><A NAME=".DEFINED"></A> <A NAME="ss10.19">10.19</A> <A HREF="ca65.html#toc10.19"><CODE>.DEF, .DEFINED</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>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 is already defined somewhere in the source file up to the
|
|
current position. Otherwise the function yields false. As an example, the
|
|
<CODE>
|
|
<A HREF="#.IFDEF">.IFDEF</A></CODE> statement may be replaced by</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.if .defined(a)
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".DESTRUCTOR"></A> <A NAME="ss10.20">10.20</A> <A HREF="ca65.html#toc10.20"><CODE>.DESTRUCTOR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Export a symbol and mark it as a module destructor. This may be used
|
|
together with the linker to build a table of destructor subroutines that
|
|
are called by the startup code.</P>
|
|
<P>Note: The linker has a feature to build a table of marked routines, but it
|
|
is your code that must call these routines, so just declaring a symbol as
|
|
constructor does nothing by itself.</P>
|
|
<P>A destructor is always exported as an absolute (16 bit) symbol. You don't
|
|
need to use an additional <CODE>.export</CODE> statement, this is implied by
|
|
<CODE>.destructor</CODE>. It may have an optional priority that is separated by a
|
|
comma. Higher numerical values mean a higher priority. If no priority is
|
|
given, the default priority of 7 is used. Be careful when assigning
|
|
priorities to your own module destructors so they won't interfere with the
|
|
ones in the cc65 library.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.destructor ModuleDone
|
|
.destructor ModDone, 16
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See the <CODE>
|
|
<A HREF="#.CONDES">.CONDES</A></CODE> and <CODE>
|
|
<A HREF="#.CONSTRUCTOR">.CONSTRUCTOR</A></CODE> commands and the separate
|
|
section
|
|
<A HREF="ca65-15.html#condes">Module constructors/destructors</A> explaining
|
|
the feature in more detail.</P>
|
|
|
|
|
|
<H2><A NAME=".DWORD"></A> <A NAME="ss10.21">10.21</A> <A HREF="ca65.html#toc10.21"><CODE>.DWORD</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define dword sized data (4 bytes) Must be followed by a sequence of
|
|
expressions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.dword $12344512, $12FA489
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".ELSE"></A> <A NAME="ss10.22">10.22</A> <A HREF="ca65.html#toc10.22"><CODE>.ELSE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Reverse the current condition.</P>
|
|
|
|
|
|
<H2><A NAME=".ELSEIF"></A> <A NAME="ss10.23">10.23</A> <A HREF="ca65.html#toc10.23"><CODE>.ELSEIF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Reverse current condition and test a new one.</P>
|
|
|
|
|
|
<H2><A NAME=".END"></A> <A NAME="ss10.24">10.24</A> <A HREF="ca65.html#toc10.24"><CODE>.END</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Forced end of assembly. Assembly stops at this point, even if the command
|
|
is read from an include file.</P>
|
|
|
|
|
|
<H2><A NAME=".ENDENUM"></A> <A NAME="ss10.25">10.25</A> <A HREF="ca65.html#toc10.25"><CODE>.ENDENUM</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>End a <CODE>
|
|
<A HREF="#.ENUM">.ENUM</A></CODE> declaration.</P>
|
|
|
|
|
|
<H2><A NAME=".ENDIF"></A> <A NAME="ss10.26">10.26</A> <A HREF="ca65.html#toc10.26"><CODE>.ENDIF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Close a <CODE>
|
|
<A HREF="#.IF">.IF...</A></CODE> or
|
|
<CODE>
|
|
<A HREF="#.ELSE">.ELSE</A></CODE> branch.</P>
|
|
|
|
|
|
<H2><A NAME=".ENDMACRO"></A> <A NAME="ss10.27">10.27</A> <A HREF="ca65.html#toc10.27"><CODE>.ENDMAC, .ENDMACRO</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>End of macro definition (see section
|
|
<A HREF="ca65-11.html#macros">Macros</A>).</P>
|
|
|
|
|
|
<H2><A NAME=".ENDPROC"></A> <A NAME="ss10.28">10.28</A> <A HREF="ca65.html#toc10.28"><CODE>.ENDPROC</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>End of local lexical level (see <CODE>
|
|
<A HREF="#.PROC">.PROC</A></CODE>).</P>
|
|
|
|
|
|
<H2><A NAME=".ENDREPEAT"></A> <A NAME="ss10.29">10.29</A> <A HREF="ca65.html#toc10.29"><CODE>.ENDREP, .ENDREPEAT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>End a <CODE>
|
|
<A HREF="#.REPEAT">.REPEAT</A></CODE> block.</P>
|
|
|
|
|
|
<H2><A NAME=".ENDSCOPE"></A> <A NAME="ss10.30">10.30</A> <A HREF="ca65.html#toc10.30"><CODE>.ENDSCOPE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>End of local lexical level (see <CODE>
|
|
<A HREF="#.SCOPE">.SCOPE</A></CODE>).</P>
|
|
|
|
|
|
<H2><A NAME=".ENDSTRUCT"></A> <A NAME="ss10.31">10.31</A> <A HREF="ca65.html#toc10.31"><CODE>.ENDSTRUCT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Ends a struct definition. See the <CODE>
|
|
<A HREF="#.STRUCT">.STRUCT</A></CODE>
|
|
command and the separate section named
|
|
<A HREF="ca65-14.html#structs">"Structs and unions"</A>.</P>
|
|
|
|
|
|
<H2><A NAME=".ENUM"></A> <A NAME="ss10.32">10.32</A> <A HREF="ca65.html#toc10.32"><CODE>.ENUM</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Start an enumeration. This directive is very similar to the C <CODE>enum</CODE>
|
|
keyword. If a name is given, a new scope is created for the enumeration,
|
|
otherwise the enumeration members are placed in the enclosing scope.</P>
|
|
<P>In the enumeration body, symbols are declared. The first symbol has a value
|
|
of zero, and each following symbol will get the value of the preceding plus
|
|
one. This behaviour may be overridden by an explicit assignment. Two symbols
|
|
may have the same value.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.enum errorcodes
|
|
no_error
|
|
file_error
|
|
parse_error
|
|
.endenum
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>Above example will create a new scope named <CODE>errorcodes</CODE> with three
|
|
symbols in it that get the values 0, 1 and 2 respectively. Another way
|
|
to write this would have been:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.scope errorcodes
|
|
no_error = 0
|
|
file_error = 1
|
|
parse_error = 2
|
|
.endscope
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>Please note that explicit scoping must be used to access the identifiers:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.word errorcodes::no_error
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>A more complex example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.enum
|
|
EUNKNOWN = -1
|
|
EOK
|
|
EFILE
|
|
EBUSY
|
|
EAGAIN
|
|
EWOULDBLOCK = EAGAIN
|
|
.endenum
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>In this example, the enumeration does not have a name, which means that the
|
|
members will be visible in the enclosing scope and can be used in this scope
|
|
without explicit scoping. The first member (<CODE>EUNKNOWN</CODE>) has the value -1.
|
|
The value for the following members is incremented by one, so <CODE>EOK</CODE> would
|
|
be zero and so on. <CODE>EWOULDBLOCK</CODE> is an alias for <CODE>EGAIN</CODE>, so it has an
|
|
override for the value using an already defined symbol.</P>
|
|
|
|
|
|
<H2><A NAME=".ERROR"></A> <A NAME="ss10.33">10.33</A> <A HREF="ca65.html#toc10.33"><CODE>.ERROR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Force an assembly error. The assembler will output an error message
|
|
preceded by "User error" and will <EM>not</EM> produce an object file.</P>
|
|
<P>This command may be used to check for initial conditions that must be
|
|
set before assembling a source file.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.if foo = 1
|
|
...
|
|
.elseif bar = 1
|
|
...
|
|
.else
|
|
.error "Must define foo or bar!"
|
|
.endif
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.WARNING">.WARNING</A></CODE> and <CODE>
|
|
<A HREF="#.OUT">.OUT</A></CODE> directives.</P>
|
|
|
|
|
|
<H2><A NAME=".EXITMACRO"></A> <A NAME="ss10.34">10.34</A> <A HREF="ca65.html#toc10.34"><CODE>.EXITMAC, .EXITMACRO</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Abort a macro expansion immediately. This command is often useful in
|
|
recursive macros. See separate section
|
|
<A HREF="ca65-11.html#macros">Macros</A>.</P>
|
|
|
|
|
|
<H2><A NAME=".EXPORT"></A> <A NAME="ss10.35">10.35</A> <A HREF="ca65.html#toc10.35"><CODE>.EXPORT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Make symbols accessible from other modules. Must be followed by a comma
|
|
separated list of symbols to export, with each one optionally followed by
|
|
an address specification. The default is to export the symbol with the
|
|
address size it actually has. The assembler will issue a warning, if the
|
|
symbol is exported with an address size smaller than the actual address
|
|
size.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.export foo
|
|
.export bar: far
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.EXPORTZP">.EXPORTZP</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".EXPORTZP"></A> <A NAME="ss10.36">10.36</A> <A HREF="ca65.html#toc10.36"><CODE>.EXPORTZP</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Make symbols accessible from other modules. Must be followed by a comma
|
|
separated list of symbols to export. The exported symbols are explicitly
|
|
marked as zero page symbols.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.exportzp foo, bar
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.EXPORT">.EXPORT</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".FARADDR"></A> <A NAME="ss10.37">10.37</A> <A HREF="ca65.html#toc10.37"><CODE>.FARADDR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define far (24 bit) address data. The command must be followed by a
|
|
sequence of (not necessarily constant) expressions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.faraddr DrawCircle, DrawRectangle, DrawHexagon
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.ADDR">.ADDR</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".FEATURE"></A> <A NAME="ss10.38">10.38</A> <A HREF="ca65.html#toc10.38"><CODE>.FEATURE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>This directive may be used to enable one or more compatibility features
|
|
of the assembler. While the use of <CODE>.FEATURE</CODE> should be avoided when
|
|
possible, it may be useful when porting sources written for other
|
|
assemblers. There is no way to switch a feature off, once you have
|
|
enabled it, so using</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.FEATURE xxx
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>will enable the feature until end of assembly is reached.</P>
|
|
<P>The following features are available:</P>
|
|
<P>
|
|
<DL>
|
|
|
|
<DT><B><CODE>at_in_identifiers</CODE></B><DD><P>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.</P>
|
|
|
|
<DT><B><CODE>dollar_in_identifiers</CODE></B><DD><P>Accept the dollar sign (`$') as a valid character in identifiers. The
|
|
at character is not allowed to start an identifier, even with this
|
|
feature enabled.</P>
|
|
|
|
<DT><B><CODE>dollar_is_pc</CODE></B><DD><P>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.</P>
|
|
|
|
<DT><B><CODE>labels_without_colons</CODE></B><DD><P>Allow labels without a trailing colon. These labels are only accepted,
|
|
if they start at the beginning of a line (no leading white space).</P>
|
|
|
|
<DT><B><CODE>leading_dot_in_identifiers</CODE></B><DD><P>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
|
|
overridden. When using this feature, you may also get into trouble if
|
|
later versions of the assembler define new keywords starting with a dot.</P>
|
|
|
|
<DT><B><CODE>loose_char_term</CODE></B><DD><P>Accept single quotes as well as double quotes as terminators for char
|
|
constants.</P>
|
|
|
|
<DT><B><CODE>loose_string_term</CODE></B><DD><P>Accept single quotes as well as double quotes as terminators for string
|
|
constants.</P>
|
|
|
|
<DT><B><CODE>missing_char_term</CODE></B><DD><P>Accept single quoted character constants where the terminating quote is
|
|
missing.
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
lda #'a
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
|
|
<B>Note:</B> This does not work in conjunction with <CODE>.FEATURE
|
|
loose_string_term</CODE>, since in this case the input would be ambiguous.</P>
|
|
|
|
<DT><B><CODE>pc_assignment</CODE></B><DD><P>Allow assignments to the PC symbol (`*' or `$' if <CODE>dollar_is_pc</CODE>
|
|
is enabled). Such an assignment is handled identical to the <CODE>
|
|
<A HREF="#.ORG">.ORG</A></CODE> 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).</P>
|
|
|
|
<DT><B><CODE>ubiquitous_idents</CODE></B><DD><P>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
|
|
same name. This does also make it possible to introduce hard to find errors
|
|
in your code, so be careful!</P>
|
|
|
|
</DL>
|
|
</P>
|
|
<P>It is also possible to specify features on the command line using the
|
|
<CODE>
|
|
<A HREF="ca65-2.html#option--feature">--feature</A></CODE> command line option.
|
|
This is useful when translating sources written for older assemblers, when
|
|
you don't want to change the source code.</P>
|
|
<P>As an example, to translate sources written for Andre Fachats xa65
|
|
assembler, the features</P>
|
|
<P>
|
|
<PRE>
|
|
labels_without_colons, pc_assignment, loose_char_term
|
|
|
|
</PRE>
|
|
</P>
|
|
<P>may be helpful. They do not make ca65 completely compatible, so you may not
|
|
be able to translate the sources without changes, even when enabling these
|
|
features. However, I have found several sources that translate without
|
|
problems when enabling these features on the command line.</P>
|
|
|
|
|
|
<H2><A NAME=".FOPT"></A> <A NAME="ss10.39">10.39</A> <A HREF="ca65.html#toc10.39"><CODE>.FILEOPT, .FOPT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Insert an option string into the object file. There are two forms of
|
|
this command, one specifies the option by a keyword, the second
|
|
specifies it as a number. Since usage of the second one needs knowledge
|
|
of the internal encoding, its use is not recommended and I will only
|
|
describe the first form here.</P>
|
|
<P>The command is followed by one of the keywords</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
author
|
|
comment
|
|
compiler
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>a comma and a string. The option is written into the object file
|
|
together with the string value. This is currently unidirectional and
|
|
there is no way to actually use these options once they are in the
|
|
object file.</P>
|
|
<P>Examples:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.fileopt comment, "Code stolen from my brother"
|
|
.fileopt compiler, "BASIC 2.0"
|
|
.fopt author, "J. R. User"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".FORCEIMPORT"></A> <A NAME="ss10.40">10.40</A> <A HREF="ca65.html#toc10.40"><CODE>.FORCEIMPORT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Import an absolute symbol from another module. The command is followed by a
|
|
comma separated list of symbols to import. The command is similar to <CODE>
|
|
<A HREF="#.IMPORT">.IMPORT</A></CODE>, but the import reference is always
|
|
written to the generated object file, even if the symbol is never referenced
|
|
(<CODE>
|
|
<A HREF="#.IMPORT">.IMPORT</A></CODE> will not generate import
|
|
references for unused symbols).</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.forceimport needthisone, needthistoo
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.IMPORT">.IMPORT</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".GLOBAL"></A> <A NAME="ss10.41">10.41</A> <A HREF="ca65.html#toc10.41"><CODE>.GLOBAL</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Declare symbols as global. Must be followed by a comma separated list of
|
|
symbols to declare. Symbols from the list, that are defined somewhere in the
|
|
source, are exported, all others are imported. Additional <CODE>
|
|
<A HREF="#.IMPORT">.IMPORT</A></CODE> or <CODE>
|
|
<A HREF="#.EXPORT">.EXPORT</A></CODE> commands for the same symbol are allowed.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.global foo, bar
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".GLOBALZP"></A> <A NAME="ss10.42">10.42</A> <A HREF="ca65.html#toc10.42"><CODE>.GLOBALZP</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Declare symbols as global. Must be followed by a comma separated list of
|
|
symbols to declare. Symbols from the list, that are defined somewhere in the
|
|
source, are exported, all others are imported. Additional <CODE>
|
|
<A HREF="#.IMPORTZP">.IMPORTZP</A></CODE> or <CODE>
|
|
<A HREF="#.EXPORTZP">.EXPORTZP</A></CODE> commands for the same symbol are allowed. The symbols
|
|
in the list are explicitly marked as zero page symbols.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.globalzp foo, bar
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".I16"></A> <A NAME="ss10.43">10.43</A> <A HREF="ca65.html#toc10.43"><CODE>.I16</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Valid only in 65816 mode. Switch the index registers to 16 bit.</P>
|
|
<P>Note: This command will not emit any code, it will tell the assembler to
|
|
create 16 bit operands for immediate operands.</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.I8">.I8</A></CODE> and <CODE>
|
|
<A HREF="#.SMART">.SMART</A></CODE> commands.</P>
|
|
|
|
|
|
<H2><A NAME=".I8"></A> <A NAME="ss10.44">10.44</A> <A HREF="ca65.html#toc10.44"><CODE>.I8</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Valid only in 65816 mode. Switch the index registers to 8 bit.</P>
|
|
<P>Note: This command will not emit any code, it will tell the assembler to
|
|
create 8 bit operands for immediate operands.</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.I16">.I16</A></CODE> and <CODE>
|
|
<A HREF="#.SMART">.SMART</A></CODE> commands.</P>
|
|
|
|
|
|
<H2><A NAME=".IF"></A> <A NAME="ss10.45">10.45</A> <A HREF="ca65.html#toc10.45"><CODE>.IF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Evaluate an expression and switch assembler output
|
|
on or off depending on the expression. The expression must be a constant
|
|
expression, that is, all operands must be defined.</P>
|
|
<P>A expression value of zero evaluates to FALSE, any other value evaluates
|
|
to TRUE.</P>
|
|
|
|
|
|
<H2><A NAME=".IFBLANK"></A> <A NAME="ss10.46">10.46</A> <A HREF="ca65.html#toc10.46"><CODE>.IFBLANK</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>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 <CODE>
|
|
<A HREF="#.ELSE">.ESLE</A></CODE>, <CODE>
|
|
<A HREF="#.ELSEIF">.ELSEIF</A></CODE> or
|
|
<CODE>
|
|
<A HREF="#.ENDIF">.ENDIF</A></CODE> directive.</P>
|
|
<P>This command is often used to check if a macro parameter was given. Since an
|
|
empty macro parameter will evaluate to nothing, the condition will evaluate
|
|
to FALSE if an empty parameter was given.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.macro arg1, arg2
|
|
.ifblank arg2
|
|
lda #arg1
|
|
.else
|
|
lda #arg2
|
|
.endif
|
|
.endmacro
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="ca65-9.html#.BLANK">.BLANK</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IFCONST"></A> <A NAME="ss10.47">10.47</A> <A HREF="ca65.html#toc10.47"><CODE>.IFCONST</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Evaluate an expression and switch assembler output
|
|
on or off depending on the constness of the expression.</P>
|
|
<P>A const expression evaluates to to TRUE, a non const expression (one
|
|
containing an imported or currently undefined symbol) evaluates to
|
|
FALSE.</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="ca65-9.html#.CONST">.CONST</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IFDEF"></A> <A NAME="ss10.48">10.48</A> <A HREF="ca65.html#toc10.48"><CODE>.IFDEF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if a symbol is defined. Must be followed by
|
|
a symbol name. The condition is true if the the given symbol is already
|
|
defined, and false otherwise.</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="#.DEFINED">.DEFINED</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IFNBLANK"></A> <A NAME="ss10.49">10.49</A> <A HREF="ca65.html#toc10.49"><CODE>.IFNBLANK</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if there are any remaining tokens in this line,
|
|
and evaluate to TRUE if this is the case, and to FALSE otherwise. If the
|
|
condition is not true, further lines are not assembled until an <CODE>
|
|
<A HREF="#.ELSE">.ELSE</A></CODE>, <CODE>
|
|
<A HREF="#.ELSEIF">.ELSEIF</A></CODE> or
|
|
<CODE>
|
|
<A HREF="#.ENDIF">.ENDIF</A></CODE> directive.</P>
|
|
<P>This command is often used to check if a macro parameter was given.
|
|
Since an empty macro parameter will evaluate to nothing, the condition
|
|
will evaluate to FALSE if an empty parameter was given.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.macro arg1, arg2
|
|
lda #arg1
|
|
.ifnblank arg2
|
|
lda #arg2
|
|
.endif
|
|
.endmacro
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="ca65-9.html#.BLANK">.BLANK</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IFNDEF"></A> <A NAME="ss10.50">10.50</A> <A HREF="ca65.html#toc10.50"><CODE>.IFNDEF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if a symbol is defined. Must be followed by
|
|
a symbol name. The condition is true if the the given symbol is not
|
|
defined, and false otherwise.</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="#.DEFINED">.DEFINED</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IFNREF"></A> <A NAME="ss10.51">10.51</A> <A HREF="ca65.html#toc10.51"><CODE>.IFNREF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if a symbol is referenced. Must be followed
|
|
by a symbol name. The condition is true if if the the given symbol was
|
|
not referenced before, and false otherwise.</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="ca65-9.html#.REFERENCED">.REFERENCED</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IFP02"></A> <A NAME="ss10.52">10.52</A> <A HREF="ca65.html#toc10.52"><CODE>.IFP02</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if the assembler is currently in 6502 mode
|
|
(see <CODE>
|
|
<A HREF="#.P02">.P02</A></CODE> command).</P>
|
|
|
|
|
|
<H2><A NAME=".IFP816"></A> <A NAME="ss10.53">10.53</A> <A HREF="ca65.html#toc10.53"><CODE>.IFP816</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if the assembler is currently in 65816 mode
|
|
(see <CODE>
|
|
<A HREF="#.P816">.P816</A></CODE> command).</P>
|
|
|
|
|
|
<H2><A NAME=".IFPC02"></A> <A NAME="ss10.54">10.54</A> <A HREF="ca65.html#toc10.54"><CODE>.IFPC02</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if the assembler is currently in 65C02 mode
|
|
(see <CODE>
|
|
<A HREF="#.PC02">.PC02</A></CODE> command).</P>
|
|
|
|
|
|
<H2><A NAME=".IFPSC02"></A> <A NAME="ss10.55">10.55</A> <A HREF="ca65.html#toc10.55"><CODE>.IFPSC02</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if the assembler is currently in 65SC02 mode
|
|
(see <CODE>
|
|
<A HREF="#.PSC02">.PSC02</A></CODE> command).</P>
|
|
|
|
|
|
<H2><A NAME=".IFREF"></A> <A NAME="ss10.56">10.56</A> <A HREF="ca65.html#toc10.56"><CODE>.IFREF</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Conditional assembly: Check if a symbol is referenced. Must be followed
|
|
by a symbol name. The condition is true if if the the given symbol was
|
|
referenced before, and false otherwise.</P>
|
|
<P>This command may be used to build subroutine libraries in include files
|
|
(you may use separate object modules for this purpose too).</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.ifref ToHex ; If someone used this subroutine
|
|
ToHex: tay ; Define subroutine
|
|
lda HexTab,y
|
|
rts
|
|
.endif
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also: <CODE>
|
|
<A HREF="ca65-9.html#.REFERENCED">.REFERENCED</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IMPORT"></A> <A NAME="ss10.57">10.57</A> <A HREF="ca65.html#toc10.57"><CODE>.IMPORT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Import a symbol from another module. The command is followed by a comma
|
|
separated list of symbols to import, with each one optionally followed by
|
|
an address specification.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.import foo
|
|
.import bar: zeropage
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.IMPORTZP">.IMPORTZP</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".IMPORTZP"></A> <A NAME="ss10.58">10.58</A> <A HREF="ca65.html#toc10.58"><CODE>.IMPORTZP</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Import a symbol from another module. The command is followed by a comma
|
|
separated list of symbols to import. The symbols are explicitly imported
|
|
as zero page symbols (that is, symbols with values in byte range).</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.importzp foo, bar
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.IMPORT">.IMPORT</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".INCBIN"></A> <A NAME="ss10.59">10.59</A> <A HREF="ca65.html#toc10.59"><CODE>.INCBIN</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Include a file as binary data. The command expects a string argument
|
|
that is the name of a file to include literally in the current segment.
|
|
In addition to that, a start offset and a size value may be specified,
|
|
separated by commas. If no size is specified, all of the file from the
|
|
start offset to end-of-file is used. If no start position is specified
|
|
either, zero is assumed (which means that the whole file is inserted).</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
; Include whole file
|
|
.incbin "sprites.dat"
|
|
|
|
; Include file starting at offset 256
|
|
.incbin "music.dat", $100
|
|
|
|
; Read 100 bytes starting at offset 200
|
|
.incbin "graphics.dat", 200, 100
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".INCLUDE"></A> <A NAME="ss10.60">10.60</A> <A HREF="ca65.html#toc10.60"><CODE>.INCLUDE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Include another file. Include files may be nested up to a depth of 16.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.include "subs.inc"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".INTERRUPTOR"></A> <A NAME="ss10.61">10.61</A> <A HREF="ca65.html#toc10.61"><CODE>.INTERRUPTOR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Export a symbol and mark it as an interruptor. This may be used together
|
|
with the linker to build a table of interruptor subroutines that are called
|
|
in an interrupt.</P>
|
|
<P>Note: The linker has a feature to build a table of marked routines, but it
|
|
is your code that must call these routines, so just declaring a symbol as
|
|
interruptor does nothing by itself.</P>
|
|
<P>An interruptor is always exported as an absolute (16 bit) symbol. You don't
|
|
need to use an additional <CODE>.export</CODE> statement, this is implied by
|
|
<CODE>.interruptor</CODE>. It may have an optional priority that is separated by a
|
|
comma. Higher numeric values mean a higher priority. If no priority is
|
|
given, the default priority of 7 is used. Be careful when assigning
|
|
priorities to your own module constructors so they won't interfere with the
|
|
ones in the cc65 library.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.interruptor IrqHandler
|
|
.interruptor Handler, 16
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See the <CODE>
|
|
<A HREF="#.CONDES">.CONDES</A></CODE> command and the separate
|
|
section
|
|
<A HREF="ca65-15.html#condes">Module constructors/destructors</A> explaining
|
|
the feature in more detail.</P>
|
|
|
|
|
|
<H2><A NAME=".LINECONT"></A> <A NAME="ss10.62">10.62</A> <A HREF="ca65.html#toc10.62"><CODE>.LINECONT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch on or off line continuations using the backslash character
|
|
before a newline. The option is off by default.
|
|
Note: Line continuations do not work in a comment. A backslash at the
|
|
end of a comment is treated as part of the comment and does not trigger
|
|
line continuation.
|
|
The command must be followed by a '+' or '-' character to switch the
|
|
option on or off respectively.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.linecont + ; Allow line continuations
|
|
|
|
lda \
|
|
#$20 ; This is legal now
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".LIST"></A> <A NAME="ss10.63">10.63</A> <A HREF="ca65.html#toc10.63"><CODE>.LIST</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Enable output to the listing. The command must be followed by a boolean
|
|
switch ("on", "off", "+" or "-") and will enable or disable listing
|
|
output.
|
|
The option has no effect if the listing is not enabled by the command line
|
|
switch -l. If -l is used, an internal counter is set to 1. Lines are output
|
|
to the listing file, if the counter is greater than zero, and suppressed if
|
|
the counter is zero. Each use of <CODE>.LIST</CODE> will increment or decrement the
|
|
counter.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.list on ; Enable listing output
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".LISTBYTES"></A> <A NAME="ss10.64">10.64</A> <A HREF="ca65.html#toc10.64"><CODE>.LISTBYTES</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Set, how many bytes are shown in the listing for one source line. The
|
|
default is 12, so the listing will show only the first 12 bytes for any
|
|
source line that generates more than 12 bytes of code or data.
|
|
The directive needs an argument, which is either "unlimited", or an
|
|
integer constant in the range 4..255.</P>
|
|
<P>Examples:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.listbytes unlimited ; List all bytes
|
|
.listbytes 12 ; List the first 12 bytes
|
|
.incbin "data.bin" ; Include large binary file
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".LOCAL"></A> <A NAME="ss10.65">10.65</A> <A HREF="ca65.html#toc10.65"><CODE>.LOCAL</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>This command may only be used inside a macro definition. It declares a
|
|
list of identifiers as local to the macro expansion.</P>
|
|
<P>A problem when using macros are labels: Since they don't change their name,
|
|
you get a "duplicate symbol" error if the macro is expanded the second time.
|
|
Labels declared with <CODE>
|
|
<A HREF="#.LOCAL">.LOCAL</A></CODE> have their
|
|
name mapped to an internal unique name (<CODE>___ABCD__</CODE>) with each macro
|
|
invocation.</P>
|
|
<P>Some other assemblers start a new lexical block inside a macro expansion.
|
|
This has some drawbacks however, since that will not allow <EM>any</EM> symbol
|
|
to be visible outside a macro, a feature that is sometimes useful. The
|
|
<CODE>
|
|
<A HREF="#.LOCAL">.LOCAL</A></CODE> command is in my eyes a better way
|
|
to address the problem.</P>
|
|
<P>You get an error when using <CODE>
|
|
<A HREF="#.LOCAL">.LOCAL</A></CODE> outside
|
|
a macro.</P>
|
|
|
|
|
|
<H2><A NAME=".LOCALCHAR"></A> <A NAME="ss10.66">10.66</A> <A HREF="ca65.html#toc10.66"><CODE>.LOCALCHAR</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Defines the character that start "cheap" local labels. You may use one
|
|
of '@' and '?' as start character. The default is '@'.</P>
|
|
<P>Cheap local labels are labels that are visible only between two non
|
|
cheap labels. This way you can reuse identifiers like "<CODE>loop</CODE>" without
|
|
using explicit lexical nesting.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.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!
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".MACPACK"></A> <A NAME="ss10.67">10.67</A> <A HREF="ca65.html#toc10.67"><CODE>.MACPACK</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Insert a predefined macro package. The command is followed by an
|
|
identifier specifying the macro package to insert. Available macro
|
|
packages are:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
atari Defines the scrcode macro.
|
|
cbm Defines the scrcode macro.
|
|
cpu Defines constants for the .CPU variable.
|
|
generic Defines generic macros like add and sub.
|
|
longbranch Defines conditional long jump macros.
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>Including a macro package twice, or including a macro package that
|
|
redefines already existing macros will lead to an error.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.macpack longbranch ; Include macro package
|
|
|
|
cmp #$20 ; Set condition codes
|
|
jne Label ; Jump long on condition
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>Macro packages are explained in more detail in section
|
|
<A HREF="ca65-12.html#macropackages">Macro packages</A>.</P>
|
|
|
|
|
|
<H2><A NAME=".MAC"></A> <A NAME="ss10.68">10.68</A> <A HREF="ca65.html#toc10.68"><CODE>.MAC, .MACRO</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Start a classic macro definition. The command is followed by an identifier
|
|
(the macro name) and optionally by a comma separated list of identifiers
|
|
that are macro parameters.</P>
|
|
<P>See section
|
|
<A HREF="ca65-11.html#macros">Macros</A>.</P>
|
|
|
|
|
|
<H2><A NAME=".ORG"></A> <A NAME="ss10.69">10.69</A> <A HREF="ca65.html#toc10.69"><CODE>.ORG</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Start a section of absolute code. The command is followed by a constant
|
|
expression that gives the new PC counter location for which the code is
|
|
assembled. Use <CODE>
|
|
<A HREF="#.RELOC">.RELOC</A></CODE> to switch back to
|
|
relocatable code.</P>
|
|
<P>Please note that you <EM>do not need</EM> this command in most cases. Placing
|
|
code at a specific address is the job of the linker, not the assembler, so
|
|
there is usually no reason to assemble code to a specific address.</P>
|
|
<P>You may not switch segments while inside a section of absolute code.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.org $7FF ; Emit code starting at $7FF
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".OUT"></A> <A NAME="ss10.70">10.70</A> <A HREF="ca65.html#toc10.70"><CODE>.OUT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Output a string to the console without producing an error. This command
|
|
is similar to <CODE>.ERROR</CODE>, however, it does not force an assembler error
|
|
that prevents the creation of an object file.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.out "This code was written by the codebuster(tm)"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.WARNING">.WARNING</A></CODE> and <CODE>
|
|
<A HREF="#.ERROR">.ERROR</A></CODE> directives.</P>
|
|
|
|
|
|
<H2><A NAME=".P02"></A> <A NAME="ss10.71">10.71</A> <A HREF="ca65.html#toc10.71"><CODE>.P02</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Enable the 6502 instruction set, disable 65SC02, 65C02 and 65816
|
|
instructions. This is the default if not overridden by the
|
|
<CODE>
|
|
<A HREF="ca65-2.html#option--cpu">--cpu</A></CODE> command line option.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.PC02">.PC02</A></CODE>, <CODE>
|
|
<A HREF="#.PSC02">.PSC02</A></CODE> and <CODE>
|
|
<A HREF="#.P816">.P816</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".P816"></A> <A NAME="ss10.72">10.72</A> <A HREF="ca65.html#toc10.72"><CODE>.P816</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Enable the 65816 instruction set. This is a superset of the 65SC02 and
|
|
6502 instruction sets.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.P02">.P02</A></CODE>, <CODE>
|
|
<A HREF="#.PSC02">.PSC02</A></CODE> and <CODE>
|
|
<A HREF="#.PC02">.PC02</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".PAGELENGTH"></A> <A NAME="ss10.73">10.73</A> <A HREF="ca65.html#toc10.73"><CODE>.PAGELEN, .PAGELENGTH</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Set the page length for the listing. Must be followed by an integer
|
|
constant. The value may be "unlimited", or in the range 32 to 127. The
|
|
statement has no effect if no listing is generated. The default value is -1
|
|
(unlimited) but may be overridden by the <CODE>--pagelength</CODE> command line
|
|
option. Beware: Since ca65 is a one pass assembler, the listing is generated
|
|
after assembly is complete, you cannot use multiple line lengths with one
|
|
source. Instead, the value set with the last <CODE>.PAGELENGTH</CODE> is used.</P>
|
|
<P>Examples:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.pagelength 66 ; Use 66 lines per listing page
|
|
|
|
.pagelength unlimited ; Unlimited page length
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".PC02"></A> <A NAME="ss10.74">10.74</A> <A HREF="ca65.html#toc10.74"><CODE>.PC02</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Enable the 65C02 instructions set. This instruction set includes all
|
|
6502 and 65SC02 instructions.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.P02">.P02</A></CODE>, <CODE>
|
|
<A HREF="#.PSC02">.PSC02</A></CODE> and <CODE>
|
|
<A HREF="#.P816">.P816</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".POPSEG"></A> <A NAME="ss10.75">10.75</A> <A HREF="ca65.html#toc10.75"><CODE>.POPSEG</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Pop the last pushed segment from the stack, and set it.</P>
|
|
<P>This command will switch back to the segment that was last pushed onto the
|
|
segment stack using the <CODE>
|
|
<A HREF="#.PUSHSEG">.PUSHSEG</A></CODE>
|
|
command, and remove this entry from the stack.</P>
|
|
<P>The assembler will print an error message if the segment stack is empty
|
|
when this command is issued.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.PUSHSEG">.PUSHSEG</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".PROC"></A> <A NAME="ss10.76">10.76</A> <A HREF="ca65.html#toc10.76"><CODE>.PROC</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Start a nested lexical level with the given name and adds a symbol with this
|
|
name to the enclosing scope. All new symbols from now on are in the local
|
|
lexical level and are accessible from outside only via
|
|
<A HREF="ca65-6.html#scopesyntax">explicit scope specification</A>. Symbols defined outside this local
|
|
level may be accessed as long as their names are not used for new symbols
|
|
inside the level. Symbols names in other lexical levels do not clash, so you
|
|
may use the same names for identifiers. The lexical level ends when the
|
|
<CODE>
|
|
<A HREF="#.ENDPROC">.ENDPROC</A></CODE> command is read. Lexical levels
|
|
may be nested up to a depth of 16 (this is an artificial limit to protect
|
|
against errors in the source).</P>
|
|
<P>Note: Macro names are always in the global level and in a separate name
|
|
space. There is no special reason for this, it's just that I've never
|
|
had any need for local macro definitions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.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
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.ENDPROC">.ENDPROC</A></CODE> and <CODE>
|
|
<A HREF="#.SCOPE">.SCOPE</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".PSC02"></A> <A NAME="ss10.77">10.77</A> <A HREF="ca65.html#toc10.77"><CODE>.PSC02</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Enable the 65SC02 instructions set. This instruction set includes all
|
|
6502 instructions.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.P02">.P02</A></CODE>, <CODE>
|
|
<A HREF="#.PC02">.PC02</A></CODE> and <CODE>
|
|
<A HREF="#.P816">.P816</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".PUSHSEG"></A> <A NAME="ss10.78">10.78</A> <A HREF="ca65.html#toc10.78"><CODE>.PUSHSEG</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Push the currently active segment onto a stack. The entries on the stack
|
|
include the name of the segment and the segment type. The stack has a size
|
|
of 16 entries.</P>
|
|
<P><CODE>.PUSHSEG</CODE> allows together with <CODE>
|
|
<A HREF="#.POPSEG">.POPSEG</A></CODE>
|
|
to switch to another segment and to restore the old segment later, without
|
|
even knowing the name and type of the current segment.</P>
|
|
<P>The assembler will print an error message if the segment stack is already
|
|
full, when this command is issued.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.POPSEG">.POPSEG</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".RELOC"></A> <A NAME="ss10.79">10.79</A> <A HREF="ca65.html#toc10.79"><CODE>.RELOC</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch back to relocatable mode. See the <CODE>
|
|
<A HREF="#.ORG">.ORG</A></CODE> command.</P>
|
|
|
|
|
|
<H2><A NAME=".REPEAT"></A> <A NAME="ss10.80">10.80</A> <A HREF="ca65.html#toc10.80"><CODE>.REPEAT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Repeat all commands between <CODE>.REPEAT</CODE> and <CODE>
|
|
<A HREF="#.ENDREPEAT">.ENDREPEAT</A></CODE> constant number of times. The command is followed by
|
|
a constant expression that tells how many times the commands in the body
|
|
should get repeated. Optionally, a comma and an identifier may be specified.
|
|
If this identifier is found in the body of the repeat statement, it is
|
|
replaced by the current repeat count (starting with zero for the first time
|
|
the body is repeated).</P>
|
|
<P><CODE>.REPEAT</CODE> statements may be nested. If you use the same repeat count
|
|
identifier for a nested <CODE>.REPEAT</CODE> statement, the one from the inner
|
|
level will be used, not the one from the outer level.</P>
|
|
<P>Example:</P>
|
|
<P>The following macro will emit a string that is "encrypted" in that all
|
|
characters of the string are XORed by the value $55.</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.macro Crypt Arg
|
|
.repeat .strlen(Arg), I
|
|
.byte .strat(Arg, I) ^ $55
|
|
.endrep
|
|
.endmacro
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.ENDREPEAT">.ENDREPEAT</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".RES"></A> <A NAME="ss10.81">10.81</A> <A HREF="ca65.html#toc10.81"><CODE>.RES</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Reserve storage. The command is followed by one or two constant
|
|
expressions. The first one is mandatory and defines, how many bytes of
|
|
storage should be defined. The second, optional expression must by a
|
|
constant byte value that will be used as value of the data. If there
|
|
is no fill value given, the linker will use the value defined in the
|
|
linker configuration file (default: zero).</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
; Reserve 12 bytes of memory with value $AA
|
|
.res 12, $AA
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".RODATA"></A> <A NAME="ss10.82">10.82</A> <A HREF="ca65.html#toc10.82"><CODE>.RODATA</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch to the RODATA segment. The name of the RODATA segment is always
|
|
"RODATA", so this is a shortcut for</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.segment "RODATA"
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>The RODATA segment is a segment that is used by the compiler for
|
|
readonly data like string constants.</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.SEGMENT">.SEGMENT</A></CODE> command.</P>
|
|
|
|
|
|
<H2><A NAME=".SCOPE"></A> <A NAME="ss10.83">10.83</A> <A HREF="ca65.html#toc10.83"><CODE>.SCOPE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Start a nested lexical level with the given name. All new symbols from now
|
|
on are in the local lexical level and are accessible from outside only via
|
|
<A HREF="ca65-6.html#scopesyntax">explicit scope specification</A>. Symbols defined
|
|
outside this local level may be accessed as long as their names are not used
|
|
for new symbols inside the level. Symbols names in other lexical levels do
|
|
not clash, so you may use the same names for identifiers. The lexical level
|
|
ends when the <CODE>
|
|
<A HREF="#.ENDSCOPE">.ENDSCOPE</A></CODE> command is
|
|
read. Lexical levels may be nested up to a depth of 16 (this is an
|
|
artificial limit to protect against errors in the source).</P>
|
|
<P>Note: Macro names are always in the global level and in a separate name
|
|
space. There is no special reason for this, it's just that I've never
|
|
had any need for local macro definitions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.scope Error ; Start new scope named Error
|
|
None = 0 ; No error
|
|
File = 1 ; File error
|
|
Parse = 2 ; Parse error
|
|
.endproc ; Close lexical level
|
|
|
|
...
|
|
lda #Error::File ; Use symbol from scope Error
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.ENDSCOPE">.ENDSCOPE</A></CODE> and <CODE>
|
|
<A HREF="#.PROC">.PROC</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".SEGMENT"></A> <A NAME="ss10.84">10.84</A> <A HREF="ca65.html#toc10.84"><CODE>.SEGMENT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch to another segment. Code and data is always emitted into a
|
|
segment, that is, a named section of data. The default segment is
|
|
"CODE". There may be up to 254 different segments per object file
|
|
(and up to 65534 per executable). There are shortcut commands for
|
|
the most common segments ("CODE", "DATA" and "BSS").</P>
|
|
<P>The command is followed by a string containing the segment name (there are
|
|
some constraints for the name - as a rule of thumb use only those segment
|
|
names that would also be valid identifiers). There may also be an optional
|
|
address size separated by a colon. See the section covering <CODE>
|
|
<A HREF="ca65-7.html#address-sizes">address sizes</A></CODE> for more information.</P>
|
|
<P>The default address size for a segment depends on the memory model specified
|
|
on the command line. The default is "absolute", which means that you don't
|
|
have to use an address size modifier in most cases.</P>
|
|
<P>"absolute" means that the is a segment with 16 bit (absolute) addressing.
|
|
That is, the segment will reside somewhere in core memory outside the zero
|
|
page. "zeropage" (8 bit) means that the segment will be placed in the zero
|
|
page and direct (short) addressing is possible for data in this segment.</P>
|
|
<P>Beware: Only labels in a segment with the zeropage attribute are marked
|
|
as reachable by short addressing. The `*' (PC counter) operator will
|
|
work as in other segments and will create absolute variable values.</P>
|
|
<P>Please note that a segment cannot have two different address sizes. A
|
|
segment specified as zeropage cannot be declared as being absolute later.</P>
|
|
<P>Examples:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.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
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.BSS">.BSS</A></CODE>, <CODE>
|
|
<A HREF="#.CODE">.CODE</A></CODE>, <CODE>
|
|
<A HREF="#.DATA">.DATA</A></CODE> and <CODE>
|
|
<A HREF="#.RODATA">.RODATA</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".SETCPU"></A> <A NAME="ss10.85">10.85</A> <A HREF="ca65.html#toc10.85"><CODE>.SETCPU</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>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 <CODE>
|
|
<A HREF="ca65-2.html#option--cpu">--cpu</A></CODE> command line option,
|
|
namely: 6502, 6502X, 65SC02, 65C02, 65816, sunplus and HuC6280. Please
|
|
note that support for the sunplus CPU is not available in the freeware
|
|
version, because the instruction set of the sunplus CPU is "proprietary
|
|
and confidential".</P>
|
|
<P>See: <CODE>
|
|
<A HREF="ca65-8.html#.CPU">.CPU</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.IFP02">.IFP02</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.IFP816">.IFP816</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.IFPC02">.IFPC02</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.IFPSC02">.IFPSC02</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.P02">.P02</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.P816">.P816</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.PC02">.PC02</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.PSC02">.PSC02</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".SMART"></A> <A NAME="ss10.86">10.86</A> <A HREF="ca65.html#toc10.86"><CODE>.SMART</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch on or off smart mode. The command must be followed by a '+' or '-'
|
|
character to switch the option on or off respectively. The default is off
|
|
(that is, the assembler doesn't try to be smart), but this default may be
|
|
changed by the -s switch on the command line.</P>
|
|
<P>In smart mode the assembler will do the following:</P>
|
|
<P>
|
|
<UL>
|
|
<LI>Track usage of the <CODE>REP</CODE> and <CODE>SEP</CODE> instructions in 65816 mode
|
|
and update the operand sizes accordingly. If the operand of such an
|
|
instruction cannot be evaluated by the assembler (for example, because
|
|
the operand is an imported symbol), a warning is issued. Beware: Since
|
|
the assembler cannot trace the execution flow this may lead to false
|
|
results in some cases. If in doubt, use the <CODE>.Inn</CODE> and <CODE>.Ann</CODE>
|
|
instructions to tell the assembler about the current settings.</LI>
|
|
<LI>In 65816 mode, replace a <CODE>RTS</CODE> instruction by <CODE>RTL</CODE> if it is
|
|
used within a procedure declared as <CODE>far</CODE>, or if the procedure has
|
|
no explicit address specification, but it is <CODE>far</CODE> because of the
|
|
memory model used.</LI>
|
|
</UL>
|
|
</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.smart ; Be smart
|
|
.smart - ; Stop being smart
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.A16">.A16</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.A8">.A8</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.I16">.I16</A></CODE>,
|
|
<CODE>
|
|
<A HREF="#.I8">.I8</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".STRUCT"></A> <A NAME="ss10.87">10.87</A> <A HREF="ca65.html#toc10.87"><CODE>.STRUCT</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Starts a struct definition. Structs are covered in a separate section named
|
|
<A HREF="ca65-14.html#structs">"Structs and unions"</A>.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.ENDSTRUCT">.ENDSTRUCT</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".SUNPLUS"></A> <A NAME="ss10.88">10.88</A> <A HREF="ca65.html#toc10.88"><CODE>.SUNPLUS</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Enable the SunPlus instructions set. This command will not work in the
|
|
freeware version of the assembler, because the instruction set is
|
|
"proprietary and confidential".</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.P02">.P02</A></CODE>, <CODE>
|
|
<A HREF="#.PSC02">.PSC02</A></CODE>, <CODE>
|
|
<A HREF="#.PC02">.PC02</A></CODE>, and
|
|
<CODE>
|
|
<A HREF="#.P816">.P816</A></CODE></P>
|
|
|
|
|
|
<H2><A NAME=".TAG"></A> <A NAME="ss10.89">10.89</A> <A HREF="ca65.html#toc10.89"><CODE>.TAG</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Allocate space for a struct or union.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.struct Point
|
|
xcoord .word
|
|
ycoord .word
|
|
.endstruct
|
|
|
|
.bss
|
|
.tag Point ; Allocate 4 bytes
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".WARNING"></A> <A NAME="ss10.90">10.90</A> <A HREF="ca65.html#toc10.90"><CODE>.WARNING</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Force an assembly warning. The assembler will output a warning message
|
|
preceded by "User warning". This warning will always be output, even if
|
|
other warnings are disabled with the <CODE>
|
|
<A HREF="ca65-2.html#option-W">-W0</A></CODE>
|
|
command line option.</P>
|
|
<P>This command may be used to output possible problems when assembling
|
|
the source file.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.macro jne target
|
|
.local L1
|
|
.ifndef target
|
|
.warning "Forward jump in jne, cannot optimize!"
|
|
beq L1
|
|
jmp target
|
|
L1:
|
|
.else
|
|
...
|
|
.endif
|
|
.endmacro
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>See also the <CODE>
|
|
<A HREF="#.ERROR">.ERROR</A></CODE> and <CODE>
|
|
<A HREF="#.OUT">.OUT</A></CODE> directives.</P>
|
|
|
|
|
|
<H2><A NAME=".WORD"></A> <A NAME="ss10.91">10.91</A> <A HREF="ca65.html#toc10.91"><CODE>.WORD</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Define word sized data. Must be followed by a sequence of (word ranged,
|
|
but not necessarily constant) expressions.</P>
|
|
<P>Example:</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.word $0D00, $AF13, _Clear
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
|
|
<H2><A NAME=".ZEROPAGE"></A> <A NAME="ss10.92">10.92</A> <A HREF="ca65.html#toc10.92"><CODE>.ZEROPAGE</CODE></A>
|
|
</H2>
|
|
|
|
|
|
<P>Switch to the ZEROPAGE segment and mark it as direct (zeropage) segment.
|
|
The name of the ZEROPAGE segment is always "ZEROPAGE", so this is a
|
|
shortcut for</P>
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
.segment "ZEROPAGE", zeropage
|
|
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
<P>Because of the "zeropage" attribute, labels declared in this segment are
|
|
addressed using direct addressing mode if possible. You <EM>must</EM> instruct
|
|
the linker to place this segment somewhere in the address range 0..$FF
|
|
otherwise you will get errors.</P>
|
|
<P>See: <CODE>
|
|
<A HREF="#.SEGMENT">.SEGMENT</A></CODE></P>
|
|
|
|
|
|
|
|
<HR>
|
|
<A HREF="ca65-11.html">Next</A>
|
|
<A HREF="ca65-9.html">Previous</A>
|
|
<A HREF="ca65.html#toc10">Contents</A>
|
|
</BODY>
|
|
</HTML>
|