Mercurial > hg-old > index.cgi

diff doc/manual/x144.html @ 153:ffef3ea07399 2.1 2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Preparing for release
author lost
date Fri, 30 Jan 2009 04:32:55 +0000
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/x144.html	Fri Jan 30 04:32:55 2009 +0000
@@ -0,0 +1,625 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<HTML
+><HEAD
+><TITLE
+>Assembler Directives</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
+REL="HOME"
+TITLE="LW Tool Chain"
+HREF="index.html"><LINK
+REL="UP"
+TITLE="LWASM"
+HREF="c35.html"><LINK
+REL="PREVIOUS"
+TITLE="Numbers and Expressions"
+HREF="x137.html"><LINK
+REL="NEXT"
+TITLE="Macros"
+HREF="x339.html"></HEAD
+><BODY
+CLASS="SECTION"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+SUMMARY="Header navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>LW Tool Chain</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="x137.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 3. LWASM</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="x339.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECTION"
+><H1
+CLASS="SECTION"
+><A
+NAME="AEN144"
+>3.6. Assembler Directives</A
+></H1
+><P
+>Various directives can be used to control the behaviour of the
+assembler or to include non-code/data in the resulting output. Those directives
+that are not described in detail in other sections of this document are
+described below.</P
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN147"
+>3.6.1. Data Directives</A
+></H2
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>FCB <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+></DT
+><DD
+><P
+>Include one or more constant bytes (separated by commas) in the output.</P
+></DD
+><DT
+>FDB <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+></DT
+><DD
+><P
+>Include one or more words (separated by commas) in the output.</P
+></DD
+><DT
+>FQB <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+></DT
+><DD
+><P
+>Include one or more double words (separated by commas) in the output.</P
+></DD
+><DT
+>FCC <CODE
+CLASS="PARAMETER"
+>string</CODE
+></DT
+><DD
+><P
+>Include a string of text in the output. The first character of the operand
+is the delimiter which must appear as the last character and cannot appear
+within the string. The string is included with no modifications&#62;</P
+></DD
+><DT
+>FCN <CODE
+CLASS="PARAMETER"
+>string</CODE
+></DT
+><DD
+><P
+>Include a NUL terminated string of text in the output. The first character of
+the operand is the delimiter which must appear as the last character and
+cannot appear within the string. A NUL byte is automatically appended to
+the string.</P
+></DD
+><DT
+>FCS <CODE
+CLASS="PARAMETER"
+>string</CODE
+></DT
+><DD
+><P
+>Include a string of text in the output with bit 7 of the final byte set. The
+first character of the operand is the delimiter which must appear as the last
+character and cannot appear within the string.</P
+></DD
+><DT
+>ZMB <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Include a number of NUL bytes in the output. The number must be fully resolvable
+during pass 1 of assembly so no forward or external references are permitted.</P
+></DD
+><DT
+>ZMD <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Include a number of zero words in the output. The number must be fully
+resolvable during pass 1 of assembly so no forward or external references are
+permitted.</P
+></DD
+><DT
+>ZMQ <CODE
+CLASS="PARAMETER"
+>expr<CODE
+CLASS="PARAMETER"
+></CODE
+></CODE
+></DT
+><DD
+><P
+>Include a number of zero double-words in the output. The number must be fully
+resolvable during pass 1 of assembly so no forward or external references are
+permitted.</P
+></DD
+><DT
+>RMB <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Reserve a number of bytes in the output. The number must be fully resolvable
+during pass 1 of assembly so no forward or external references are permitted.
+The value of the bytes is undefined.</P
+></DD
+><DT
+>RMD <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Reserve a number of words in the output. The number must be fully
+resolvable during pass 1 of assembly so no forward or external references are
+permitted. The value of the words is undefined.</P
+></DD
+><DT
+>RMQ <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Reserve a number of double-words in the output. The number must be fully
+resolvable during pass 1 of assembly so no forward or external references are
+permitted. The value of the double-words is undefined.</P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN211"
+>3.6.2. Address Definition</A
+></H2
+><P
+>The directives in this section all control the addresses of symbols
+or the assembly process itself.</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>ORG <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Set the assembly address. The address must be fully resolvable on the
+first pass so no external or forward references are permitted. ORG is not
+permitted within sections when outputting to object files. For the DECB
+target, each ORG directive after which output is generated will cause
+a new preamble to be output. ORG is only used to determine the addresses
+of symbols when the raw target is used.</P
+></DD
+><DT
+><CODE
+CLASS="PARAMETER"
+>sym</CODE
+> EQU <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>, <CODE
+CLASS="PARAMETER"
+>sym</CODE
+> = <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Define the value of <CODE
+CLASS="PARAMETER"
+>sym</CODE
+> to be <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>.</P
+></DD
+><DT
+><CODE
+CLASS="PARAMETER"
+>sym</CODE
+> SET <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Define the value of <CODE
+CLASS="PARAMETER"
+>sym</CODE
+> to be <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>.
+Unlike EQU, SET permits symbols to be defined multiple times as long as SET
+is used for all instances. Use of the symbol before the first SET statement
+that sets its value is undefined.</P
+></DD
+><DT
+>SETDP <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Inform the assembler that it can assume the DP register contains
+<CODE
+CLASS="PARAMETER"
+>expr</CODE
+>. This directive is only advice to the assembler
+to determine whether an address is in the direct page and has no effect
+on the contents of the DP register. The value must be fully resolved during
+the first assembly pass because it affects the sizes of subsequent instructions.</P
+><P
+>This directive has no effect in the object file target.</P
+></DD
+><DT
+>ALIGN <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>Force the current assembly address to be a multiple of <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>.
+A series of NUL bytes is output to force the alignment, if required. The
+alignment value must be fully resolved on the first pass because it affects
+the addresses of subsquent instructions.</P
+><P
+>This directive is not suitable for inclusion in the middle of actual
+code. It is intended to appear where the bytes output will not be executed.</P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN253"
+>3.6.3. Conditional Assembly</A
+></H2
+><P
+>Portions of the source code can be excluded or included based on conditions
+known at assembly time. Conditionals can be nested arbitrarily deeply. The
+directives associated with conditional assembly are described in this section.</P
+><P
+>All conditionals must be fully bracketed. That is, every conditional
+statement must eventually be followed by an ENDC at the same level of nesting.</P
+><P
+>Conditional expressions are only evaluated on the first assembly pass.
+It is not possible to game the assembly process by having a conditional
+change its value between assembly passes. Thus there is not and never will
+be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>IFEQ <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> evaluates to zero, the conditional
+will be considered true.</P
+></DD
+><DT
+>IFNE <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>, IF <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> evaluates to a non-zero value, the conditional
+will be considered true.</P
+></DD
+><DT
+>IFGT <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> evaluates to a value greater than zero, the conditional
+will be considered true.</P
+></DD
+><DT
+>IFGE <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> evaluates to a value greater than or equal to zero, the conditional
+will be considered true.</P
+></DD
+><DT
+>IFLT <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> evaluates to a value less than zero, the conditional
+will be considered true.</P
+></DD
+><DT
+>IFLE <CODE
+CLASS="PARAMETER"
+>expr</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> evaluates to a value less than or equal to zero , the conditional
+will be considered true.</P
+></DD
+><DT
+>IFDEF <CODE
+CLASS="PARAMETER"
+>sym</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>sym</CODE
+> is defined at this point in the assembly
+process, the conditional
+will be considered true.</P
+></DD
+><DT
+>IFNDEF <CODE
+CLASS="PARAMETER"
+>sym</CODE
+></DT
+><DD
+><P
+>If <CODE
+CLASS="PARAMETER"
+>sym</CODE
+> is not defined at this point in the assembly
+process, the conditional
+will be considered true.</P
+></DD
+><DT
+>ELSE</DT
+><DD
+><P
+>If the preceding conditional at the same level of nesting was false, the
+statements following will be assembled. If the preceding conditional at
+the same level was true, the statements following will not be assembled.
+Note that the preceding conditional might have been another ELSE statement
+although this behaviour is not guaranteed to be supported in future versions
+of LWASM.</P
+></DD
+><DT
+>ENDC</DT
+><DD
+><P
+>This directive marks the end of a conditional construct. Every conditional
+construct must end with an ENDC directive.</P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN317"
+>3.6.4. Miscelaneous Directives</A
+></H2
+><P
+>This section includes directives that do not fit into the other
+categories.</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>INCLUDE <CODE
+CLASS="PARAMETER"
+>filename</CODE
+></DT
+><DD
+><P
+>Include the contents of <CODE
+CLASS="PARAMETER"
+>filename</CODE
+> at this point in
+the assembly as though it were a part of the file currently being processed.
+Note that whitespace cannot appear in the name of the file.</P
+></DD
+><DT
+>END <CODE
+CLASS="PARAMETER"
+>[expr]</CODE
+></DT
+><DD
+><P
+>This directive causes the assembler to stop assembling immediately as though
+it ran out of input. For the DECB target only, <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>
+can be used to set the execution address of the resulting binary. For all
+other targets, specifying <CODE
+CLASS="PARAMETER"
+>expr</CODE
+> will cause an error.</P
+></DD
+><DT
+>ERROR <CODE
+CLASS="PARAMETER"
+>string</CODE
+></DT
+><DD
+><P
+>Causes a custom error message to be printed at this line. This will cause
+assembly to fail. This directive is most useful inside conditional constructs
+to cause assembly to fail if some condition that is known bad happens.</P
+></DD
+></DL
+></DIV
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="x137.html"
+ACCESSKEY="P"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+ACCESSKEY="H"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="x339.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>Numbers and Expressions</TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="c35.html"
+ACCESSKEY="U"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Macros</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file