Mercurial > hg > index.cgi

diff docs/manual/x193.html @ 153:83b7b4ce3bbd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added prebuilt manual to repository to avoid failures to include it during releases
author lost@l-w.ca
date Sat, 27 Aug 2011 00:23:19 -0600
parents
children
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/manual/x193.html	Sat Aug 27 00:23:19 2011 -0600
@@ -0,0 +1,844 @@
+<!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="c45.html"><LINK
+REL="PREVIOUS"
+TITLE="Numbers and Expressions"
+HREF="x185.html"><LINK
+REL="NEXT"
+TITLE="Macros"
+HREF="x476.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="x185.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="x476.html"
+ACCESSKEY="N"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECTION"
+><H1
+CLASS="SECTION"
+><A
+NAME="AEN193"
+>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="AEN196"
+>3.6.1. Data Directives</A
+></H2
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>FCB <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+>, .DB <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+>, .BYTE <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
+>, .DW <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+>, .WORD <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
+>, .QUAD <CODE
+CLASS="PARAMETER"
+>expr[,...]</CODE
+>, .4BYTE <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
+>, .ASCII <CODE
+CLASS="PARAMETER"
+>string</CODE
+>, .STR <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
+>, .ASCIZ <CODE
+CLASS="PARAMETER"
+>string</CODE
+>, .STRZ <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
+>, .ASCIS <CODE
+CLASS="PARAMETER"
+>string</CODE
+>, .STRS <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
+>, .BLKB <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>, .DS <CODE
+CLASS="PARAMETER"
+>expr</CODE
+>, .RS <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
+><DT
+>INCLUDEBIN <CODE
+CLASS="PARAMETER"
+>filename</CODE
+></DT
+><DD
+><P
+>Treat the contents of <CODE
+CLASS="PARAMETER"
+>filename</CODE
+> as a string of bytes to
+be included literally at the current assembly point. This has the same effect
+as converting the file contents to a series of FCB statements and including
+those at the current assembly point.</P
+><P
+> If <CODE
+CLASS="PARAMETER"
+>filename</CODE
+> beings with a /, the file name
+will be taken as absolute.  Otherwise, the current directory will be
+searched followed by the search path in the order specified.</P
+><P
+> Please note that absolute path detection including drive letters will
+not function correctly on Windows platforms.  Non-absolute inclusion will
+work, however.</P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN299"
+>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
+>[,<CODE
+CLASS="PARAMETER"
+>value</CODE
+>]</DT
+><DD
+><P
+>Force the current assembly address to be a multiple of
+<CODE
+CLASS="PARAMETER"
+>expr</CODE
+>.  If <CODE
+CLASS="PARAMETER"
+>value</CODE
+> is not
+specified, a series of NUL bytes is output to force the alignment, if
+required.  Otherwise, the low order 8 bits of <CODE
+CLASS="PARAMETER"
+>value</CODE
+>
+will be used as the fill.  The alignment value must be fully resolved on the
+first pass because it affects the addresses of subsquent instructions. 
+However, <CODE
+CLASS="PARAMETER"
+>value</CODE
+> may include forward references; as
+long as it resolves to a constant for the second pass, the value will be
+accepted.</P
+><P
+>Unless <CODE
+CLASS="PARAMETER"
+>value</CODE
+> is specified as something like $12,
+this directive is not suitable for inclusion in the middle of actual code. 
+The default padding value is $00 which is intended to be used within data
+blocks.  </P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN346"
+>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. Due to the underlying architecture
+of LWASM, there is no possible utility to IFP1 and IFP2, nor can they, as of LWASM 3.0, actually
+be implemented meaningfully. Thus there is not and never will
+be any equivalent of IFP1 or IFP2 as provided by other assemblers. Use of those opcodes
+will throw a warning and be ignored.</P
+><P
+>It is important to note that if a conditional does not resolve to a constant
+during the first parsing pass, an error will be thrown. This is unavoidable because the assembler
+must make a decision about which source to include and which source to exclude at this stage.
+Thus, expressions that work normally elsewhere will not work for conditions.</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="AEN411"
+>3.6.4. OS9 Target Directives</A
+></H2
+><P
+>This section includes directives that apply solely to the OS9
+target.</P
+><P
+></P
+><DIV
+CLASS="VARIABLELIST"
+><DL
+><DT
+>OS9 <CODE
+CLASS="PARAMETER"
+>syscall</CODE
+></DT
+><DD
+><P
+>&#13;This directive generates a call to the specified system call. <CODE
+CLASS="PARAMETER"
+>syscall</CODE
+> may be an arbitrary expression.&#13;</P
+></DD
+><DT
+>MOD <CODE
+CLASS="PARAMETER"
+>size</CODE
+>,<CODE
+CLASS="PARAMETER"
+>name</CODE
+>,<CODE
+CLASS="PARAMETER"
+>type</CODE
+>,<CODE
+CLASS="PARAMETER"
+>flags</CODE
+>,<CODE
+CLASS="PARAMETER"
+>execoff</CODE
+>,<CODE
+CLASS="PARAMETER"
+>datasize</CODE
+></DT
+><DD
+><P
+>&#13;This tells LWASM that the beginning of the actual module is here. It will
+generate a module header based on the parameters specified.  It will also
+begin calcuating the module CRC.&#13;</P
+><P
+>&#13;The precise meaning of the various parameters is beyond the scope of this
+document since it is not a tutorial on OS9 module programming.&#13;</P
+></DD
+><DT
+>EMOD</DT
+><DD
+><P
+>&#13;This marks the end of a module and causes LWASM to emit the calculated CRC
+for the module.&#13;</P
+></DD
+></DL
+></DIV
+></DIV
+><DIV
+CLASS="SECTION"
+><H2
+CLASS="SECTION"
+><A
+NAME="AEN436"
+>3.6.5. 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
+>, USE <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 if whitespace appears in the name of the file,
+you must enclose <CODE
+CLASS="PARAMETER"
+>filename</CODE
+> in quotes.</P
+><P
+>Note that the USE variation is provided only for compatibility with other
+assemblers. It is recommended to use the INCLUDE variation.</P
+><P
+>If <CODE
+CLASS="PARAMETER"
+>filename</CODE
+> begins with a &quot;/&quot;, it is
+interpreted as an absolute path. If it does not, the search path will be used
+to find the file. First, the directory containing the file that contains this
+directive. (Includes within an included file are relative to the included file,
+not the file that included it.) If the file is not found there, the include path
+is searched. If it is still not found, an error will be thrown. Note that the
+current directory as understood by your shell or operating system is not searched.</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. Everything
+from the directive to the end of the line is considered the error message.</P
+></DD
+><DT
+>WARNING <CODE
+CLASS="PARAMETER"
+>string</CODE
+></DT
+><DD
+><P
+>Causes a custom warning message to be printed at this line. This will not cause
+assembly to fail. This directive is most useful inside conditional constructs
+or include files to alert the programmer to a deprecated feature being used
+or some other condition that may cause trouble later, but which may, in fact,
+not cause any trouble.</P
+></DD
+><DT
+>.MODULE <CODE
+CLASS="PARAMETER"
+>string</CODE
+></DT
+><DD
+><P
+>This directive is ignored for most output targets. If the output target
+supports encoding a module name into it, <CODE
+CLASS="PARAMETER"
+>string</CODE
+>
+will be used as the module name.</P
+><P
+>As of version 3.0, no supported output targets support this directive.</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="x185.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="x476.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="c45.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