LWTools Old Repo: doc/manual.docbook.sgml annotate

annotate doc/manual.docbook.sgml @ 276:23034db7dd8a 2.5

fixed expression 'slots' to not store null on a pass 1 store

author	lost
date	Mon, 31 Aug 2009 08:39:36 +0000
parents	b43e3e23583c
children	6e2d03188d24

rev	line source
109 f21a5593a661 Updated docs lost parents: diff changeset	1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN">
f21a5593a661 Updated docs lost parents: diff changeset	2 <book>
f21a5593a661 Updated docs lost parents: diff changeset	3 <bookinfo>
f21a5593a661 Updated docs lost parents: diff changeset	4 <title>LW Tool Chain</title>
f21a5593a661 Updated docs lost parents: diff changeset	5 <author><firstname>William</firstname><surname>Astle</surname></author>
f21a5593a661 Updated docs lost parents: diff changeset	6 <copyright><year>2009</year><holder>William Astle</holder></copyright>
f21a5593a661 Updated docs lost parents: diff changeset	7 </bookinfo>
f21a5593a661 Updated docs lost parents: diff changeset	8 <chapter>
f21a5593a661 Updated docs lost parents: diff changeset	9
f21a5593a661 Updated docs lost parents: diff changeset	10 <title>Introduction</title>
f21a5593a661 Updated docs lost parents: diff changeset	11
f21a5593a661 Updated docs lost parents: diff changeset	12 <para>
f21a5593a661 Updated docs lost parents: diff changeset	13 The LW tool chain provides utilities for building binaries for MC6809 and
f21a5593a661 Updated docs lost parents: diff changeset	14 HD6309 CPUs. The tool chain includes a cross-assembler and a cross-linker
f21a5593a661 Updated docs lost parents: diff changeset	15 which support several styles of output.
f21a5593a661 Updated docs lost parents: diff changeset	16 </para>
f21a5593a661 Updated docs lost parents: diff changeset	17
f21a5593a661 Updated docs lost parents: diff changeset	18 <section>
f21a5593a661 Updated docs lost parents: diff changeset	19 <title>History</title>
f21a5593a661 Updated docs lost parents: diff changeset	20 <para>
f21a5593a661 Updated docs lost parents: diff changeset	21 For a long time, I have had an interest in creating an operating system for
f21a5593a661 Updated docs lost parents: diff changeset	22 the Coco3. I finally started working on that project around the beginning of
f21a5593a661 Updated docs lost parents: diff changeset	23 2006. I had a number of assemblers I could choose from. Eventually, I settled
f21a5593a661 Updated docs lost parents: diff changeset	24 on one and started tinkering. After a while, I realized that assembler was not
f21a5593a661 Updated docs lost parents: diff changeset	25 going to be sufficient due to lack of macros and issues with forward references.
f21a5593a661 Updated docs lost parents: diff changeset	26 Then I tried another which handled forward references correctly but still did
f21a5593a661 Updated docs lost parents: diff changeset	27 not support macros. I looked around at other assemblers and they all lacked
f21a5593a661 Updated docs lost parents: diff changeset	28 one feature or another that I really wanted for creating my operating system.
f21a5593a661 Updated docs lost parents: diff changeset	29 </para>
f21a5593a661 Updated docs lost parents: diff changeset	30
f21a5593a661 Updated docs lost parents: diff changeset	31 <para>
f21a5593a661 Updated docs lost parents: diff changeset	32 The solution seemed clear at that point. I am a fair programmer so I figured
f21a5593a661 Updated docs lost parents: diff changeset	33 I could write an assembler that would do everything I wanted an assembler to
f21a5593a661 Updated docs lost parents: diff changeset	34 do. Thus the LWASM probject was born. After more than two years of on and off
f21a5593a661 Updated docs lost parents: diff changeset	35 work, version 1.0 of LWASM was released in October of 2008.
f21a5593a661 Updated docs lost parents: diff changeset	36 </para>
f21a5593a661 Updated docs lost parents: diff changeset	37
f21a5593a661 Updated docs lost parents: diff changeset	38 <para>
f21a5593a661 Updated docs lost parents: diff changeset	39 As the aforementioned operating system project progressed further, it became
f21a5593a661 Updated docs lost parents: diff changeset	40 clear that while assembling the whole project through a single file was doable,
f21a5593a661 Updated docs lost parents: diff changeset	41 it was not practical. When I found myself playing some fancy games with macros
f21a5593a661 Updated docs lost parents: diff changeset	42 in a bid to simulate sections, I realized I needed a means of assembling
f21a5593a661 Updated docs lost parents: diff changeset	43 source files separately and linking them later. This spawned a major development
f21a5593a661 Updated docs lost parents: diff changeset	44 effort to add an object file support to LWASM. It also spawned the LWLINK
f21a5593a661 Updated docs lost parents: diff changeset	45 project to provide a means to actually link the files.
f21a5593a661 Updated docs lost parents: diff changeset	46 </para>
f21a5593a661 Updated docs lost parents: diff changeset	47
f21a5593a661 Updated docs lost parents: diff changeset	48 </section>
f21a5593a661 Updated docs lost parents: diff changeset	49
f21a5593a661 Updated docs lost parents: diff changeset	50 </chapter>
f21a5593a661 Updated docs lost parents: diff changeset	51
f21a5593a661 Updated docs lost parents: diff changeset	52 <chapter>
f21a5593a661 Updated docs lost parents: diff changeset	53 <title>Output Formats</title>
f21a5593a661 Updated docs lost parents: diff changeset	54
f21a5593a661 Updated docs lost parents: diff changeset	55 <para>
f21a5593a661 Updated docs lost parents: diff changeset	56 The LW tool chain supports multiple output formats. Each format has its
f21a5593a661 Updated docs lost parents: diff changeset	57 advantages and disadvantages. Each format is described below.
f21a5593a661 Updated docs lost parents: diff changeset	58 </para>
f21a5593a661 Updated docs lost parents: diff changeset	59
f21a5593a661 Updated docs lost parents: diff changeset	60 <section>
f21a5593a661 Updated docs lost parents: diff changeset	61 <title>Raw Binaries</title>
f21a5593a661 Updated docs lost parents: diff changeset	62 <para>
f21a5593a661 Updated docs lost parents: diff changeset	63 A raw binary is simply a string of bytes. There are no headers or other
f21a5593a661 Updated docs lost parents: diff changeset	64 niceties. Both LWLINK and LWASM support generating raw binaries. ORG directives
f21a5593a661 Updated docs lost parents: diff changeset	65 in the source code only serve to set the addresses that will be used for
f21a5593a661 Updated docs lost parents: diff changeset	66 symbols but otherwise have no direct impact on the resulting binary.
f21a5593a661 Updated docs lost parents: diff changeset	67 </para>
f21a5593a661 Updated docs lost parents: diff changeset	68
f21a5593a661 Updated docs lost parents: diff changeset	69 </section>
f21a5593a661 Updated docs lost parents: diff changeset	70 <section>
f21a5593a661 Updated docs lost parents: diff changeset	71 <title>DECB Binaries</title>
f21a5593a661 Updated docs lost parents: diff changeset	72
f21a5593a661 Updated docs lost parents: diff changeset	73 <para>A DECB binary is compatible with the LOADM command in Disk Extended
f21a5593a661 Updated docs lost parents: diff changeset	74 Color Basic on the CoCo. They are also compatible with CLOADM from Extended
f21a5593a661 Updated docs lost parents: diff changeset	75 Color Basic. These binaries include the load address of the binary as well
f21a5593a661 Updated docs lost parents: diff changeset	76 as encoding an execution address. These binaries may contain multiple loadable
f21a5593a661 Updated docs lost parents: diff changeset	77 sections, each of which has its own load address.</para>
f21a5593a661 Updated docs lost parents: diff changeset	78
f21a5593a661 Updated docs lost parents: diff changeset	79 <para>
f21a5593a661 Updated docs lost parents: diff changeset	80 Each binary starts with a preamble. Each preamble is five bytes long. The
f21a5593a661 Updated docs lost parents: diff changeset	81 first byte is zero. The next two bytes specify the number of bytes to load
f21a5593a661 Updated docs lost parents: diff changeset	82 and the last two bytes specify the address to load the bytes at. Then, a
f21a5593a661 Updated docs lost parents: diff changeset	83 string of bytes follows. After this string of bytes, there may be another
f21a5593a661 Updated docs lost parents: diff changeset	84 preamble or a postamble. A postamble is also five bytes in length. The first
f21a5593a661 Updated docs lost parents: diff changeset	85 byte of the postamble is $FF, the next two are zero, and the last two are
f21a5593a661 Updated docs lost parents: diff changeset	86 the execution address for the binary.
f21a5593a661 Updated docs lost parents: diff changeset	87 </para>
f21a5593a661 Updated docs lost parents: diff changeset	88
f21a5593a661 Updated docs lost parents: diff changeset	89 <para>
f21a5593a661 Updated docs lost parents: diff changeset	90 Both LWASM and LWLINK can output this format.
f21a5593a661 Updated docs lost parents: diff changeset	91 </para>
f21a5593a661 Updated docs lost parents: diff changeset	92 </section>
f21a5593a661 Updated docs lost parents: diff changeset	93
f21a5593a661 Updated docs lost parents: diff changeset	94 <section>
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	95 <title>OS9 Modules</title>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	96 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	97
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	98 Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	99 basically the same as for other assemblers. A module starts with the MOD
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	100 directive and ends with the EMOD directive. The OS9 directive is provided
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	101 as a shortcut for writing system calls.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	102
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	103 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	104
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	105 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	106
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	107 LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	108 that the common practice of using "ifp1" around the inclusion of the OS9Defs
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	109 file is discouraged as it is pointless and can lead to unintentional
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	110 problems and phasing errors. Because LWASM reads each file exactly once,
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	111 there is no benefit to restricting the inclusion to the first assembly pass.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	112
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	113 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	114
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	115 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	116
240 b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	117 It is also critical to understand that unlike many OS9 assemblers, LWASM
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	118 does NOT maintain a separate data address counter. Thus, you must define
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	119 all your data offsets and so on outside of the mod/emod segment. It is,
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	120 therefore, likely that source code targeted at other assemblers will require
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	121 edits to build correctly.
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	122
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	123 </para>
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	124
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	125 <para>
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target lost parents: 237 diff changeset	126
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	127 LWLINK does not, yet, have the ability to create OS9 modules from object
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	128 files.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	129
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	130 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	131 </section>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	132
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	133 <section>
109 f21a5593a661 Updated docs lost parents: diff changeset	134 <title>Object Files</title>
f21a5593a661 Updated docs lost parents: diff changeset	135 <para>LWASM supports generating a proprietary object file format which is
f21a5593a661 Updated docs lost parents: diff changeset	136 described in <xref linkend="objchap">. LWLINK is then used to link these
f21a5593a661 Updated docs lost parents: diff changeset	137 object files into a final binary in any of LWLINK's supported binary
f21a5593a661 Updated docs lost parents: diff changeset	138 formats.</para>
f21a5593a661 Updated docs lost parents: diff changeset	139
f21a5593a661 Updated docs lost parents: diff changeset	140 <para>Object files also support the concept of sections which are not valid
f21a5593a661 Updated docs lost parents: diff changeset	141 for other output types. This allows related code from each object file
f21a5593a661 Updated docs lost parents: diff changeset	142 linked to be collapsed together in the final binary.</para>
f21a5593a661 Updated docs lost parents: diff changeset	143
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	144 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	145 Object files are very flexible in that they allow references that are not
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	146 known at assembly time to be resolved at link time. However, because the
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	147 addresses of such references are not known at assembly time, there is no way
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	148 for the assembler to deduce that an eight bit addressing mode is possible.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	149 That means the assember will default to using sixteen bit addressing
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	150 whenever an external or cross-section reference is used.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	151 </para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	152
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	153 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	154 As of LWASM 2.4, it is possible to force direct page addressing for an
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	155 external reference. Care must be taken to ensure the resulting addresses
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	156 are really in the direct page since the linker does not know what the direct
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	157 page is supposed to be and does not emit errors for byte overflows.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	158 </para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	159
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	160 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	161 It is also possible to use external references in an eight bit immediate
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	162 mode instruction. In this case, only the low order eight bits will be used.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	163 Again, no byte overflows will be flagged.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	164 </para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	165
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	166
109 f21a5593a661 Updated docs lost parents: diff changeset	167 </section>
f21a5593a661 Updated docs lost parents: diff changeset	168
f21a5593a661 Updated docs lost parents: diff changeset	169 </chapter>
f21a5593a661 Updated docs lost parents: diff changeset	170
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	171 <chapter>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	172 <title>LWASM</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	173 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	174 The LWTOOLS assembler is called LWASM. This chapter documents the various
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	175 features of the assembler. It is not, however, a tutorial on 6x09 assembly
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	176 language programming.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	177 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	178
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	179 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	180 <title>Command Line Options</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	181 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	182 The binary for LWASM is called "lwasm". Note that the binary is in lower
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	183 case. lwasm takes the following command line arguments.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	184 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	185
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	186 <variablelist>
231 10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	187
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	188 <varlistentry>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	189 <term><option>--6309</option></term>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	190 <term><option>-3</option></term>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	191 <listitem>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	192 <para>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	193 This will cause the assembler to accept the additional instructions available
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	194 on the 6309 processor. This is the default mode; this option is provided for
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	195 completeness and to override preset command arguments.
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	196 </para>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	197 </listitem>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	198 </varlistentry>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	199
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	200 <varlistentry>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	201 <term><option>--6809</option></term>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	202 <term><option>-9</option></term>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	203 <listitem>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	204 <para>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	205 This will cause the assembler to reject instructions that are only available
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	206 on the 6309 processor.
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	207 </para>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	208 </listitem>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	209 </varlistentry>
10abe422efce Documented the --6309 and --6809 options lost parents: 227 diff changeset	210
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	211 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	212 <term><option>--decb</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	213 <term><option>-b</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	214 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	215 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	216 Select the DECB output format target. Equivalent to <option>--format=decb</option>.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	217 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	218 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	219 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	220
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	221 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	222 <term><option>--format=type</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	223 <term><option>-f type</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	224 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	225 <para>
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	226 Select the output format. Valid values are <option>obj</option> for the
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	227 object file target, <option>decb</option> for the DECB LOADM format,
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	228 <option>os9</option> for creating OS9 modules, and <option>raw</option> for
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	229 a raw binary.
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	230 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	231 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	232 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	233
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	234 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	235 <term><option>--list[=file]</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	236 <term><option>-l[file]</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	237 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	238 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	239 Cause LWASM to generate a listing. If <option>file</option> is specified,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	240 the listing will go to that file. Otherwise it will go to the standard output
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	241 stream. By default, no listing is generated.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	242 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	243 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	244 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	245
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	246 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	247 <term><option>--obj</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	248 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	249 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	250 Select the proprietary object file format as the output target.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	251 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	252 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	253 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	254
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	255 <varlistentry>
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	256 <term><option>--output=FILE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	257 <term><option>-o FILE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	258 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	259 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	260 This option specifies the name of the output file. If not specified, the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	261 default is <option>a.out</option>.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	262 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	263 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	264 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	265
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	266 <varlistentry>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	267 <term><option>--pragma=pragma</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	268 <term><option>-p pragma</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	269 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	270 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	271 Specify assembler pragmas. Multiple pragmas are separated by commas. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	272 pragmas accepted are the same as for the PRAGMA assembler directive described
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	273 below.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	274 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	275 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	276 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	277
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	278 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	279 <term><option>--raw</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	280 <term><option>-r</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	281 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	282 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	283 Select raw binary as the output target.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	284 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	285 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	286 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	287
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	288 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	289 <term><option>--help</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	290 <term><option>-?</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	291 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	292 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	293 Present a help screen describing the command line options.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	294 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	295 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	296 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	297
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	298 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	299 <term><option>--usage</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	300 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	301 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	302 Provide a summary of the command line options.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	303 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	304 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	305 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	306
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	307 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	308 <term><option>--version</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	309 <term><option>-V</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	310 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	311 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	312 Display the software version.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	313 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	314 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	315 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	316
146 6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	317 <varlistentry>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	318 <term><option>--debug</option></term>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	319 <term><option>-d</option></term>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	320 <listitem>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	321 <para>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	322 Increase the debugging level. Only really useful to people hacking on the
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	323 LWASM source code itself.
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	324 </para>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	325 </listitem>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	326 </varlistentry>
6c0a30278982 Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 145 diff changeset	327
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	328 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	329
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	330 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	331
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	332 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	333 <title>Dialects</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	334 <para>
233 efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	335 LWASM supports all documented MC6809 instructions as defined by Motorola.
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	336 It also supports all known HD6309 instructions. While there is general
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	337 agreement on the pneumonics for most of the 6309 instructions, there is some
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	338 variance with the block transfer instructions. TFM for all four variations
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	339 seems to have gained the most traction and, thus, this is the form that is
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	340 recommended for LWASM. However, it also supports COPY, COPY-, IMP, EXP,
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	341 TFRP, TFRM, TFRS, and TFRR. It further adds COPY+ as a synomym for COPY,
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	342 IMPLODE for IMP, and EXPAND for EXP.
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	343 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	344
233 efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	345 <para>By default, LWASM accepts 6309 instructions. However, using the
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	346 <parameter>--6809</parameter> parameter, you can cause it to throw errors on
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	347 6309 instructions instead.</para>
efda73d44e1b Updated discussion of assembly dialects lost parents: 232 diff changeset	348
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	349 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	350 The standard addressing mode specifiers are supported. These are the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	351 hash sign ("#") for immediate mode, the less than sign ("<") for forced
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	352 eight bit modes, and the greater than sign (">") for forced sixteen bit modes.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	353 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	354
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	355 <para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	356 Additionally, LWASM supports using the asterisk ("*") to indicate
751b99efb1fc Updated docs lost parents: 159 diff changeset	357 base page addressing. This should not be used in hand-written source code,
751b99efb1fc Updated docs lost parents: 159 diff changeset	358 however, because it is non-standard and may or may not be present in future
751b99efb1fc Updated docs lost parents: 159 diff changeset	359 versions of LWASM.
751b99efb1fc Updated docs lost parents: 159 diff changeset	360 </para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	361
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	362 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	363
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	364 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	365 <title>Source Format</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	366
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	367 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	368 LWASM accepts plain text files in a relatively free form. It can handle
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	369 lines terminated with CR, LF, CRLF, or LFCR which means it should be able
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	370 to assemble files on any platform on which it compiles.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	371 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	372 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	373 Each line may start with a symbol. If a symbol is present, there must not
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	374 be any whitespace preceding it. It is legal for a line to contain nothing
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	375 but a symbol.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	376 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	377 The op code is separated from the symbol by whitespace. If there is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	378 no symbol, there must be at least one white space character preceding it.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	379 If applicable, the operand follows separated by whitespace. Following the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	380 opcode and operand is an optional comment.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	381 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	382 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	383 A comment can also be introduced with a * or a ;. The comment character is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	384 optional for end of statement comments. However, if a symbol is the only
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	385 thing present on the line other than the comment, the comment character is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	386 mandatory to prevent the assembler from interpreting the comment as an opcode.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	387 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	388
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	389 <para>
175 f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	390 For compatibility with the output generated by some C preprocessors, LWASM
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	391 will also ignore lines that begin with a #. This should not be used as a general
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	392 comment character, however.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	393 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	394
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	395 <para>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	396 The opcode is not treated case sensitively. Neither are register names in
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	397 the operand fields. Symbols, however, are case sensitive.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	398 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	399
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	400 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	401 LWASM does not support line numbers in the file.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	402 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	403
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	404 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	405
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	406 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	407 <title>Symbols</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	408
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	409 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	410 Symbols have no length restriction. They may contain letters, numbers, dots,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	411 dollar signs, and underscores. They must start with a letter, dot, or
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	412 underscore.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	413 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	414
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	415 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	416 LWASM also supports the concept of a local symbol. A local symbol is one
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	417 which contains either a "?" or a "@", which can appear anywhere in the symbol.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	418 The scope of a local symbol is determined by a number of factors. First,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	419 each included file gets its own local symbol scope. A blank line will also
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	420 be considered a local scope barrier. Macros each have their own local symbol
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	421 scope as well (which has a side effect that you cannot use a local symbol
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	422 as an argument to a macro). There are other factors as well. In general,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	423 a local symbol is restricted to the block of code it is defined within.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	424 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	425
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	426 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	427 By default, unless assembling to the os9 target, a "$" in the symbol will
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	428 also make it local. This can be controlled by the "dollarlocal" and
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	429 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, For
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	430 the os9 target, a "$" in the symbol will not make it considered local while
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	431 for all other targets it will.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	432 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	433
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	434 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	435
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	436 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	437 <title>Numbers and Expressions</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	438 <para>
175 f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	439
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	440 Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	441 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	442 Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	443 "o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	444 with "H". No prefix or suffix is required for decimal numbers but they can
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	445 be prefixed with "&" if desired. Any constant which begins with a letter
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	446 must be expressed with the correct prefix base identifier or be prefixed
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	447 with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	448 Numbers are not case sensitive.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	449
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	450 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	451
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	452 <para> A symbol may appear at any point where a number is acceptable. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	453 special symbol "*" can be used to represent the starting address of the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	454 current source line within expressions. </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	455
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	456 <para>The ASCII value of a character can be included by prefixing it with a
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	457 single quote ('). The ASCII values of two characters can be included by
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	458 prefixing the characters with a quote (").</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	459
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	460 <para>
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	461
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	462 LWASM supports the following basic binary operators: +, -, *, /, and %.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	463 These represent addition, subtraction, multiplication, division, and
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	464 modulus. It also supports unary negation and unary 1's complement (- and ^
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	465 respectively). It is also possible to use ~ for the unary 1's complement
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	466 operator. For completeness, a unary positive (+) is supported though it is
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	467 a no-op. LWASM also supports using \|, &, and ^ for bitwise or, bitwise and,
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	468 and bitwise exclusive or respectively.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	469
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	470 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	471
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	472 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	473
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	474 Operator precedence follows the usual rules. Multiplication, division, and
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	475 modulus take precedence over addition and subtraction. Unary operators take
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	476 precedence over binary operators. Bitwise operators are lower precdence
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	477 than addition and subtraction. To force a specific order of evaluation,
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	478 parentheses can be used in the usual manner.
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	479
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	480 </para>
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	481
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	482 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	483
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	484 As of LWASM 2.5, the operators && and \|\| are recognized for boolean and and
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	485 boolean or respectively. They will return either 0 or 1 (false or true).
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	486 They have the lowest precedence of all the binary operators.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	487
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	488 </para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	489
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	490 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	491
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	492 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	493 <title>Assembler Directives</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	494 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	495 Various directives can be used to control the behaviour of the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	496 assembler or to include non-code/data in the resulting output. Those directives
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	497 that are not described in detail in other sections of this document are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	498 described below.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	499 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	500
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	501 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	502 <title>Data Directives</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	503 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	504 <varlistentry><term>FCB <parameter>expr[,...]</parameter></term>
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	505 <term>.DB <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	506 <term>.BYTE <parameter>expr[,...]</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	507 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	508 <para>Include one or more constant bytes (separated by commas) in the output.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	509 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	510 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	511
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	512 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	513 <term>FDB <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	514 <term>.DW <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	515 <term>.WORD <parameter>expr[,...]</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	516 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	517 <para>Include one or more words (separated by commas) in the output.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	518 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	519 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	520
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	521 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	522 <term>FQB <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	523 <term>.QUAD <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	524 <term>.4BYTE <parameter>expr[,...]</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	525 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	526 <para>Include one or more double words (separated by commas) in the output.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	527 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	528 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	529
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	530 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	531 <term>FCC <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	532 <term>.ASCII <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	533 <term>.STR <parameter>string</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	534 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	535 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	536 Include a string of text in the output. The first character of the operand
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	537 is the delimiter which must appear as the last character and cannot appear
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	538 within the string. The string is included with no modifications>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	539 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	540 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	541 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	542
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	543 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	544 <term>FCN <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	545 <term>.ASCIZ <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	546 <term>.STRZ <parameter>string</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	547 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	548 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	549 Include a NUL terminated string of text in the output. The first character of
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	550 the operand is the delimiter which must appear as the last character and
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	551 cannot appear within the string. A NUL byte is automatically appended to
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	552 the string.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	553 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	554 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	555 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	556
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	557 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	558 <term>FCS <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	559 <term>.ASCIS <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	560 <term>.STRS <parameter>string</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	561 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	562 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	563 Include a string of text in the output with bit 7 of the final byte set. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	564 first character of the operand is the delimiter which must appear as the last
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	565 character and cannot appear within the string.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	566 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	567 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	568 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	569
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	570 <varlistentry><term>ZMB <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	571 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	572 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	573 Include a number of NUL bytes in the output. The number must be fully resolvable
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	574 during pass 1 of assembly so no forward or external references are permitted.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	575 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	576 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	577 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	578
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	579 <varlistentry><term>ZMD <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	580 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	581 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	582 Include a number of zero words in the output. The number must be fully
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	583 resolvable during pass 1 of assembly so no forward or external references are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	584 permitted.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	585 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	586 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	587 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	588
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	589 <varlistentry><term>ZMQ <parameter>expr<parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	590 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	591 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	592 Include a number of zero double-words in the output. The number must be fully
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	593 resolvable during pass 1 of assembly so no forward or external references are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	594 permitted.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	595 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	596 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	597 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	598
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	599 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	600 <term>RMB <parameter>expr</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	601 <term>.BLKB <parameter>expr</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	602 <term>.DS <parameter>expr</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	603 <term>.RS <parameter>expr</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	604 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	605 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	606 Reserve a number of bytes in the output. The number must be fully resolvable
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	607 during pass 1 of assembly so no forward or external references are permitted.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	608 The value of the bytes is undefined.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	609 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	610 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	611 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	612
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	613 <varlistentry><term>RMD <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	614 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	615 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	616 Reserve a number of words in the output. The number must be fully
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	617 resolvable during pass 1 of assembly so no forward or external references are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	618 permitted. The value of the words is undefined.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	619 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	620 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	621 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	622
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	623 <varlistentry><term>RMQ <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	624 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	625 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	626 Reserve a number of double-words in the output. The number must be fully
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	627 resolvable during pass 1 of assembly so no forward or external references are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	628 permitted. The value of the double-words is undefined.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	629 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	630 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	631 </varlistentry>
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	632
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	633 <varlistentry>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	634 <term>INCLUDEBIN <parameter>filename</parameter></term>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	635 <listitem>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	636 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	637 Treat the contents of <parameter>filename</parameter> as a string of bytes to
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	638 be included literally at the current assembly point. This has the same effect
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	639 as converting the file contents to a series of FCB statements and including
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	640 those at the current assembly point.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	641 </para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	642 </listitem>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	643 </varlistentry>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	644
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	645 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	646
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	647 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	648
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	649 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	650 <title>Address Definition</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	651 <para>The directives in this section all control the addresses of symbols
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	652 or the assembly process itself.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	653
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	654 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	655 <varlistentry><term>ORG <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	656 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	657 <para>Set the assembly address. The address must be fully resolvable on the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	658 first pass so no external or forward references are permitted. ORG is not
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	659 permitted within sections when outputting to object files. For the DECB
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	660 target, each ORG directive after which output is generated will cause
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	661 a new preamble to be output. ORG is only used to determine the addresses
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	662 of symbols when the raw target is used.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	663 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	664 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	665 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	666
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	667 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	668 <term><parameter>sym</parameter> EQU <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	669 <term><parameter>sym</parameter> = <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	670 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	671 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	672 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	673 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	674
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	675 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	676 <term><parameter>sym</parameter> SET <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	677 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	678 <para>Define the value of <parameter>sym</parameter> to be <parameter>expr</parameter>.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	679 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	680 is used for all instances. Use of the symbol before the first SET statement
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	681 that sets its value is undefined.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	682 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	683 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	684
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	685 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	686 <term>SETDP <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	687 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	688 <para>Inform the assembler that it can assume the DP register contains
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	689 <parameter>expr</parameter>. This directive is only advice to the assembler
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	690 to determine whether an address is in the direct page and has no effect
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	691 on the contents of the DP register. The value must be fully resolved during
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	692 the first assembly pass because it affects the sizes of subsequent instructions.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	693 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	694 <para>This directive has no effect in the object file target.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	695 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	696 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	697 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	698
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	699 <varlistentry>
235 aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	700 <term>ALIGN <parameter>expr</parameter>[,<parameter>value</parameter>]</term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	701 <listitem>
235 aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	702
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	703 <para>Force the current assembly address to be a multiple of
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	704 <parameter>expr</parameter>. If <parameter>value</parameter> is not
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	705 specified, a series of NUL bytes is output to force the alignment, if
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	706 required. Otherwise, the low order 8 bits of <parameter>value</parameter>
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	707 will be used as the fill. The alignment value must be fully resolved on the
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	708 first pass because it affects the addresses of subsquent instructions.
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	709 However, <parameter>value</parameter> may include forward references; as
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	710 long as it resolves to a constant for the second pass, the value will be
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	711 accepted.</para>
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	712
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	713 <para>Unless <parameter>value</parameter> is specified as something like $12,
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	714 this directive is not suitable for inclusion in the middle of actual code.
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	715 The default padding value is $00 which is intended to be used within data
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	716 blocks. </para>
aa0056ca7319 Added a padding value for the ALIGN directive lost parents: 233 diff changeset	717
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	718 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	719 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	720
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	721 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	722
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	723 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	724
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	725 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	726 <title>Conditional Assembly</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	727 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	728 Portions of the source code can be excluded or included based on conditions
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	729 known at assembly time. Conditionals can be nested arbitrarily deeply. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	730 directives associated with conditional assembly are described in this section.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	731 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	732 <para>All conditionals must be fully bracketed. That is, every conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	733 statement must eventually be followed by an ENDC at the same level of nesting.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	734 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	735 <para>Conditional expressions are only evaluated on the first assembly pass.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	736 It is not possible to game the assembly process by having a conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	737 change its value between assembly passes. Thus there is not and never will
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	738 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	739
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	740 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	741 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	742 <term>IFEQ <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	743 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	744 <para>If <parameter>expr</parameter> evaluates to zero, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	745 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	746 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	747 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	748 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	749
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	750 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	751 <term>IFNE <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	752 <term>IF <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	753 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	754 <para>If <parameter>expr</parameter> evaluates to a non-zero value, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	755 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	756 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	757 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	758 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	759
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	760 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	761 <term>IFGT <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	762 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	763 <para>If <parameter>expr</parameter> evaluates to a value greater than zero, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	764 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	765 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	766 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	767 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	768
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	769 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	770 <term>IFGE <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	771 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	772 <para>If <parameter>expr</parameter> evaluates to a value greater than or equal to zero, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	773 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	774 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	775 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	776 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	777
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	778 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	779 <term>IFLT <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	780 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	781 <para>If <parameter>expr</parameter> evaluates to a value less than zero, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	782 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	783 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	784 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	785 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	786
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	787 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	788 <term>IFLE <parameter>expr</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	789 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	790 <para>If <parameter>expr</parameter> evaluates to a value less than or equal to zero , the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	791 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	792 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	793 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	794 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	795
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	796 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	797 <term>IFDEF <parameter>sym</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	798 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	799 <para>If <parameter>sym</parameter> is defined at this point in the assembly
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	800 process, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	801 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	802 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	803 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	804 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	805
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	806 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	807 <term>IFNDEF <parameter>sym</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	808 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	809 <para>If <parameter>sym</parameter> is not defined at this point in the assembly
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	810 process, the conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	811 will be considered true.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	812 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	813 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	814 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	815
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	816 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	817 <term>ELSE</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	818 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	819 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	820 If the preceding conditional at the same level of nesting was false, the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	821 statements following will be assembled. If the preceding conditional at
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	822 the same level was true, the statements following will not be assembled.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	823 Note that the preceding conditional might have been another ELSE statement
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	824 although this behaviour is not guaranteed to be supported in future versions
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	825 of LWASM.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	826 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	827 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	828
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	829 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	830 <term>ENDC</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	831 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	832 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	833 This directive marks the end of a conditional construct. Every conditional
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	834 construct must end with an ENDC directive.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	835 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	836 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	837 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	838
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	839 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	840 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	841
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	842 <section>
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	843 <title>OS9 Target Directives</title>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	844
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	845 <para>This section includes directives that apply solely to the OS9
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	846 target.</para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	847
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	848 <variablelist>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	849
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	850 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	851 <term>OS9 <parameter>syscall</parameter></term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	852 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	853 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	854
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	855 This directive generates a call to the specified system call. <parameter>syscall</parameter> may be an arbitrary expression.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	856
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	857 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	858 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	859 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	860
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	861 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	862 <term>MOD <parameter>size</parameter>,<parameter>name</parameter>,<parameter>type</parameter>,<parameter>flags</parameter>,<parameter>execoff</parameter>,<parameter>datasize</parameter></term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	863 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	864 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	865
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	866 This tells LWASM that the beginning of the actual module is here. It will
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	867 generate a module header based on the parameters specified. It will also
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	868 begin calcuating the module CRC.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	869
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	870 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	871
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	872 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	873
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	874 The precise meaning of the various parameters is beyond the scope of this
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	875 document since it is not a tutorial on OS9 module programming.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	876
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	877 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	878
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	879 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	880 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	881
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	882 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	883 <term>EMOD</term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	884 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	885 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	886
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	887 This marks the end of a module and causes LWASM to emit the calculated CRC
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	888 for the module.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	889
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	890 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	891 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	892
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	893 </variablelist>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	894 </section>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	895
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	896 <section>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	897 <title>Miscelaneous Directives</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	898
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	899 <para>This section includes directives that do not fit into the other
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	900 categories.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	901
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	902 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	903
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	904 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	905 <term>INCLUDE <parameter>filename</parameter></term>
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	906 <term>USE <parameter>filename</parameter></term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	907
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	908 <listitem> <para> Include the contents of <parameter>filename</parameter> at
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	909 this point in the assembly as though it were a part of the file currently
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	910 being processed. Note that if whitespace appears in the name of the file,
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	911 you must enclose <parameter>filename</parameter> in quotes.
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	912 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	913
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	914 <para>
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	915 Note that the USE variation is provided only for compatibility with other
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	916 assemblers. It is recommended to use the INCLUDE variation.</para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	917
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	918 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	919 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	920
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	921 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	922 <term>END <parameter>[expr]</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	923 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	924 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	925 This directive causes the assembler to stop assembling immediately as though
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	926 it ran out of input. For the DECB target only, <parameter>expr</parameter>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	927 can be used to set the execution address of the resulting binary. For all
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	928 other targets, specifying <parameter>expr</parameter> will cause an error.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	929 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	930 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	931 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	932
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	933 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	934 <term>ERROR <parameter>string</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	935 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	936 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	937 Causes a custom error message to be printed at this line. This will cause
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	938 assembly to fail. This directive is most useful inside conditional constructs
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	939 to cause assembly to fail if some condition that is known bad happens.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	940 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	941 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	942 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	943
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	944 <varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	945 <term>.MODULE <parameter>string</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	946 <listitem>
751b99efb1fc Updated docs lost parents: 159 diff changeset	947 <para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	948 This directive is ignored for most output targets. If the output target
751b99efb1fc Updated docs lost parents: 159 diff changeset	949 supports encoding a module name into it, <parameter>string</parameter>
751b99efb1fc Updated docs lost parents: 159 diff changeset	950 will be used as the module name.
751b99efb1fc Updated docs lost parents: 159 diff changeset	951 </para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	952 <para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	953 As of version 2.2, no supported output targets support this directive.
751b99efb1fc Updated docs lost parents: 159 diff changeset	954 </para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	955 </listitem>
751b99efb1fc Updated docs lost parents: 159 diff changeset	956 </varlistentry>
751b99efb1fc Updated docs lost parents: 159 diff changeset	957
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	958 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	959 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	960
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	961 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	962
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	963 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	964 <title>Macros</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	965 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	966 LWASM is a macro assembler. A macro is simply a name that stands in for a
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	967 series of instructions. Once a macro is defined, it is used like any other
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	968 assembler directive. Defining a macro can be considered equivalent to adding
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	969 additional assembler directives.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	970 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	971 <para>Macros my accept parameters. These parameters are referenced within
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	972 a macro by the a backslash ("\") followed by a digit 1 through 9 for the first
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	973 through ninth parameters. They may also be referenced by enclosing the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	974 decimal parameter number in braces ("{num}"). These parameter references
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	975 are replaced with the verbatim text of the parameter passed to the macro. A
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	976 reference to a non-existent parameter will be replaced by an empty string.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	977 Macro parameters are expanded everywhere on each source line. That means
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	978 the parameter to a macro could be used as a symbol or it could even appear
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	979 in a comment or could cause an entire source line to be commented out
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	980 when the macro is expanded.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	981 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	982 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	983 Parameters passed to a macro are separated by commas and the parameter list
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	984 is terminated by any whitespace. This means that neither a comma nor whitespace
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	985 may be included in a macro parameter.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	986 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	987 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	988 Macro expansion is done recursively. That is, within a macro, macros are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	989 expanded. This can lead to infinite loops in macro expansion. If the assembler
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	990 hangs for a long time while assembling a file that uses macros, this may be
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	991 the reason.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	992
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	993 <para>Each macro expansion receives its own local symbol context which is not
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	994 inherited by any macros called by it nor is it inherited from the context
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	995 the macro was instantiated in. That means it is possible to use local symbols
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	996 within macros without having them collide with symbols in other macros or
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	997 outside the macro itself. However, this also means that using a local symbol
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	998 as a parameter to a macro, while legal, will not do what it would seem to do
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	999 as it will result in looking up the local symbol in the macro's symbol context
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1000 rather than the enclosing context where it came from, likely yielding either
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1001 an undefined symbol error or bizarre assembly results.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1002 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1003 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1004 Note that there is no way to define a macro as local to a symbol context. All
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1005 macros are part of the global macro namespace. However, macros have a separate
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1006 namespace from symbols so it is possible to have a symbol with the same name
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1007 as a macro.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1008 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1009
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1010 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1011 Macros are defined only during the first pass. Macro expansion also
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1012 only occurs during the first pass. On the second pass, the macro
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1013 definition is simply ignored. Macros must be defined before they are used.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1014 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1015
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1016 <para>The following directives are used when defining macros.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1017
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1018 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1019 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1020 <term><parameter>macroname</parameter> MACRO</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1021 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1022 <para>This directive is used to being the definition of a macro called
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1023 <parameter>macroname</parameter>. If <parameter>macroname</parameter> already
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1024 exists, it is considered an error. Attempting to define a macro within a
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1025 macro is undefined. It may work and it may not so the behaviour should not
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1026 be relied upon.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1027 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1028 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1029 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1030
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1031 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1032 <term>ENDM</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1033 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1034 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1035 This directive indicates the end of the macro currently being defined. It
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1036 causes the assembler to resume interpreting source lines as normal.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1037 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1038 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1039 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1040
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1041 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1042
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1043 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1044 <title>Object Files and Sections</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1045 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1046 The object file target is very useful for large project because it allows
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1047 multiple files to be assembled independently and then linked into the final
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1048 binary at a later time. It allows only the small portion of the project
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1049 that was modified to be re-assembled rather than requiring the entire set
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1050 of source code to be available to the assembler in a single assembly process.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1051 This can be particularly important if there are a large number of macros,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1052 symbol definitions, or other metadata that uses resources at assembly time.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1053 By far the largest benefit, however, is keeping the source files small enough
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1054 for a mere mortal to find things in them.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1055 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1056
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1057 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1058 With multi-file projects, there needs to be a means of resolving references to
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1059 symbols in other source files. These are known as external references. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1060 addresses of these symbols cannot be known until the linker joins all the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1061 object files into a single binary. This means that the assembler must be
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1062 able to output the object code without knowing the value of the symbol. This
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1063 places some restrictions on the code generated by the assembler. For
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1064 example, the assembler cannot generate direct page addressing for instructions
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1065 that reference external symbols because the address of the symbol may not
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1066 be in the direct page. Similarly, relative branches and PC relative addressing
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1067 cannot be used in their eight bit forms. Everything that must be resolved
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1068 by the linker must be assembled to use the largest address size possible to
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1069 allow the linker to fill in the correct value at link time. Note that the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1070 same problem applies to absolute address references as well, even those in
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1071 the same source file, because the address is not known until link time.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1072 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1073
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1074 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1075 It is often desired in multi-file projects to have code of various types grouped
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1076 together in the final binary generated by the linker as well. The same applies
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1077 to data. In order for the linker to do that, the bits that are to be grouped
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1078 must be tagged in some manner. This is where the concept of sections comes in.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1079 Each chunk of code or data is part of a section in the object file. Then,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1080 when the linker reads all the object files, it coalesces all sections of the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1081 same name into a single section and then considers it as a unit.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1082 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1083
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1084 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1085 The existence of sections, however, raises a problem for symbols even
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1086 within the same source file. Thus, the assembler must treat symbols from
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1087 different sections within the same source file in the same manner as external
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1088 symbols. That is, it must leave them for the linker to resolve at link time,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1089 with all the limitations that entails.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1090 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1091
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1092 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1093 In the object file target mode, LWASM requires all source lines that
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1094 cause bytes to be output to be inside a section. Any directives that do
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1095 not cause any bytes to be output can appear outside of a section. This includes
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1096 such things as EQU or RMB. Even ORG can appear outside a section. ORG, however,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1097 makes no sense within a section because it is the linker that determines
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1098 the starting address of the section's code, not the assembler.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1099 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1100
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1101 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1102 All symbols defined globally in the assembly process are local to the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1103 source file and cannot be exported. All symbols defined within a section are
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1104 considered local to the source file unless otherwise explicitly exported.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1105 Symbols referenced from external source files must be declared external,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1106 either explicitly or by asking the assembler to assume that all undefined
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1107 symbols are external.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1108 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1109
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1110 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1111 It is often handy to define a number of memory addresses that will be
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1112 used for data at run-time but which need not be included in the binary file.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1113 These memory addresses are not initialized until run-time, either by the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1114 program itself or by the program loader, depending on the operating environment.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1115 Such sections are often known as BSS sections. LWASM supports generating
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1116 sections with a BSS attribute set which causes the section definition including
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1117 symbols exported from that section and those symbols required to resolve
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1118 references from the local file, but with no actual code in the object file.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1119 It is illegal for any source lines within a BSS flagged section to cause any
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1120 bytes to be output.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1121 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1122
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1123 <para>The following directives apply to section handling.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1124
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1125 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1126 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1127 <term>SECTION <parameter>name[,flags]</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1128 <term>SECT <parameter>name[,flags]</parameter></term>
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	1129 <term>.AREA <parameter>name[,flags]</parameter></term>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1130 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1131 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1132 Instructs the assembler that the code following this directive is to be
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1133 considered part of the section <parameter>name</parameter>. A section name
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1134 may appear multiple times in which case it is as though all the code from
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1135 all the instances of that section appeared adjacent within the source file.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1136 However, <parameter>flags</parameter> may only be specified on the first
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1137 instance of the section.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1138 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1139 <para>There is a single flag supported in <parameter>flags</parameter>. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1140 flag <parameter>bss</parameter> will cause the section to be treated as a BSS
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1141 section and, thus, no code will be included in the object file nor will any
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1142 bytes be permitted to be output.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1143 <para>
159 71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1144 If the section name is "bss" or ".bss" in any combination of upper and
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1145 lower case, the section is assumed to be a BSS section. In that case,
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1146 the flag <parameter>!bss</parameter> can be used to override this assumption.
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1147 </para>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1148 <para>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1149 If assembly is already happening within a section, the section is implicitly
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1150 ended and the new section started. This is not considered an error although
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1151 it is recommended that all sections be explicitly closed.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1152 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1153 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1154 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1155
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1156 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1157 <term>ENDSECTION</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1158 <term>ENDSECT</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1159 <term>ENDS</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1160 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1161 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1162 This directive ends the current section. This puts assembly outside of any
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1163 sections until the next SECTION directive.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1164 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1165 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1166
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1167 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1168 <term><parameter>sym</parameter> EXTERN</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1169 <term><parameter>sym</parameter> EXTERNAL</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1170 <term><parameter>sym</parameter> IMPORT</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1171 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1172 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1173 This directive defines <parameter>sym</parameter> as an external symbol.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1174 This directive may occur at any point in the source code. EXTERN definitions
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1175 are resolved on the first pass so an EXTERN definition anywhere in the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1176 source file is valid for the entire file. The use of this directive is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1177 optional when the assembler is instructed to assume that all undefined
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1178 symbols are external. In fact, in that mode, if the symbol is referenced
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1179 before the EXTERN directive, an error will occur.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1180 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1181 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1182 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1183
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1184 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1185 <term><parameter>sym</parameter> EXPORT</term>
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	1186 <term><parameter>sym</parameter> .GLOBL</term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	1187
751b99efb1fc Updated docs lost parents: 159 diff changeset	1188 <term>EXPORT <parameter>sym</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	1189 <term>.GLOBL <parameter>sym</parameter></term>
751b99efb1fc Updated docs lost parents: 159 diff changeset	1190
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1191 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1192 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1193 This directive defines <parameter>sym</parameter> as an exported symbol.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1194 This directive may occur at any point in the source code, even before the
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1195 definition of the exported symbol.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1196 </para>
167 751b99efb1fc Updated docs lost parents: 159 diff changeset	1197 <para>
751b99efb1fc Updated docs lost parents: 159 diff changeset	1198 Note that <parameter>sym</parameter> may appear as the operand or as the
751b99efb1fc Updated docs lost parents: 159 diff changeset	1199 statement's symbol. If there is a symbol on the statement, that will
751b99efb1fc Updated docs lost parents: 159 diff changeset	1200 take precedence over any operand that is present.
751b99efb1fc Updated docs lost parents: 159 diff changeset	1201 </para>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1202 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1203 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1204
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1205 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1206
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1207 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1208
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1209 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1210 <title>Assembler Modes and Pragmas</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1211 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1212 There are a number of options that affect the way assembly is performed.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1213 Some of these options can only be specified on the command line because
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1214 they determine something absolute about the assembly process. These include
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1215 such things as the output target. Other things may be switchable during
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1216 the assembly process. These are known as pragmas and are, by definition,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1217 not portable between assemblers.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1218 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1219
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1220 <para>LWASM supports a number of pragmas that affect code generation or
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1221 otherwise affect the behaviour of the assembler. These may be specified by
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1222 way of a command line option or by assembler directives. The directives
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1223 are as follows.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1224 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1225
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1226 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1227 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1228 <term>PRAGMA <parameter>pragma[,...]</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1229 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1230 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1231 Specifies that the assembler should bring into force all <parameter>pragma</parameter>s
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1232 specified. Any unrecognized pragma will cause an assembly error. The new
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1233 pragmas will take effect immediately. This directive should be used when
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1234 the program will assemble incorrectly if the pragma is ignored or not supported.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1235 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1236 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1237 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1238
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1239 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1240 <term>*PRAGMA <parameter>pragma[,...]</parameter></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1241 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1242 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1243 This is identical to the PRAGMA directive except no error will occur with
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1244 unrecognized or unsupported pragmas. This directive, by virtue of starting
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1245 with a comment character, will also be ignored by assemblers that do not
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1246 support this directive. Use this variation if the pragma is not required
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1247 for correct functioning of the code.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1248 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1249 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1250 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1251 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1252
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1253 <para>Each pragma supported has a positive version and a negative version.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1254 The positive version enables the pragma while the negative version disables
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1255 it. The negatitve version is simply the positive version with "no" prefixed
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1256 to it. For instance, "pragma" vs. "nopragma". Only the positive version is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1257 listed below.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1258
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1259 <para>Pragmas are not case sensitive.</para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1260
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1261 <variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1262 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1263 <term>index0tonone</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1264 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1265 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1266 When in force, this pragma enables an optimization affecting indexed addressing
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1267 modes. When the offset expression in an indexed mode evaluates to zero but is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1268 not explicity written as 0, this will replace the operand with the equivalent
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1269 no offset mode, thus creating slightly faster code. Because of the advantages
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1270 of this optimization, it is enabled by default.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1271 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1272 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1273 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1274
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1275 <varlistentry>
159 71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1276 <term>cescapes</term>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1277 <listitem>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1278 <para>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1279 This pragma will cause strings in the FCC, FCS, and FCN pseudo operations to
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1280 have C-style escape sequences interpreted. The one departure from the official
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1281 spec is that unrecognized escape sequences will return either the character
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1282 immediately following the backslash or some undefined value. Do not rely
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1283 on the behaviour of undefined escape sequences.
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1284 </para>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1285 </listitem>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1286 </varlistentry>
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1287
71561c12b20b Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss lost parents: 150 diff changeset	1288 <varlistentry>
227 4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1289 <term>importundefexport</term>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1290 <listitem>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1291 <para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1292 This pragma is only valid for targets that support external references. When
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1293 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1294 to be exported is not defined. This is provided for compatibility with the
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1295 output of gcc6809 and should not be used in hand written code. Because of
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1296 the confusion this pragma can cause, it is disabled by default.
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1297 </para>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1298 </listitem>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1299 </varlistentry>
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1300
4c60c3a09597 Various updates to the manual lost parents: 186 diff changeset	1301 <varlistentry>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1302 <term>undefextern</term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1303 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1304 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1305 This pragma is only valid for targets that support external references. When in
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1306 force, if the assembler sees an undefined symbol on the second pass, it will
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1307 automatically define it as an external symbol. This automatic definition will
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1308 apply for the remainder of the assembly process, even if the pragma is
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1309 subsequently turned off. Because this behaviour would be potentially surprising,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1310 this pragma defaults to off.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1311 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1312 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1313 The primary use for this pragma is for projects that share a large number of
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1314 symbols between source files. In such cases, it is impractical to enumerate
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1315 all the external references in every source file. This allows the assembler
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1316 and linker to do the heavy lifting while not preventing a particular source
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1317 module from defining a local symbol of the same name as an external symbol
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1318 if it does not need the external symbol. (This pragma will not cause an
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1319 automatic external definition if there is already a locally defined symbol.)
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1320 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1321 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1322 This pragma will often be specified on the command line for large projects.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1323 However, depending on the specific dynamics of the project, it may be sufficient
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1324 for one or two files to use this pragma internally.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1325 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1326 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1327 </varlistentry>
237 dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1328
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1329 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1330 <term>dollarlocal</term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1331 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1332
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1333 <para>When set, a "$" in a symbol makes it local. When not set, "$" does not
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1334 cause a symbol to be local. It is set by default except when using the OS9
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1335 target.</para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1336
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1337 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1338 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1339
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1340 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1341 <term>dollarnotlocal</term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1342 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1343
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1344 <para> This is the same as the "dollarlocal" pragma except its sense is
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1345 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1346 "nodollarlocal" and "dollarnotlocal" are equivalent. </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1347
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1348 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1349 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM lost parents: 235 diff changeset	1350
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1351 </variablelist>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1352
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1353 </section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1354
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1355 </chapter>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1356
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1357 <chapter>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1358 <title>LWLINK</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1359 <para>
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1360 The LWTOOLS linker is called LWLINK. This chapter documents the various features
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1361 of the linker.
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1362 </para>
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1363
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1364 <section>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1365 <title>Command Line Options</title>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1366 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1367 The binary for LWLINK is called "lwlink". Note that the binary is in lower
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1368 case. lwlink takes the following command line arguments.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1369 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1370 <variablelist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1371 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1372 <term><option>--decb</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1373 <term><option>-b</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1374 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1375 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1376 Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1377 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1378 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1379 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1380
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1381 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1382 <term><option>--output=FILE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1383 <term><option>-o FILE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1384 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1385 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1386 This option specifies the name of the output file. If not specified, the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1387 default is <option>a.out</option>.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1388 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1389 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1390 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1391
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1392 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1393 <term><option>--format=TYPE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1394 <term><option>-f TYPE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1395 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1396 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1397 This option specifies the output format. Valid values are <option>decb</option>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1398 and <option>raw</option>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1399 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1400 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1401 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1402
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1403 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1404 <term><option>--raw</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1405 <term><option>-r</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1406 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1407 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1408 This option specifies the raw output format.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1409 It is equivalent to <option>--format=raw</option>.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1410 and <option>raw</option>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1411 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1412 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1413 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1414
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1415 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1416 <term><option>--script=FILE</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1417 <term><option>-s</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1418 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1419 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1420 This option allows specifying a linking script to override the linker's
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1421 built in defaults.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1422 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1423 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1424 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1425
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1426 <varlistentry>
186 bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1427 <term><option>--section-base=SECT=BASE</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1428 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1429 <para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1430 Cause section SECT to load at base address BASE. This will be prepended
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1431 to the built-in link script. It is ignored if a link script is provided.
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1432 </para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1433 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1434 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1435
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1436 <varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1437 <term><option>--map=FILE</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1438 <term><option>-m FILE</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1439 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1440 <para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1441 This will output a description of the link result to FILE.
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1442 </para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1443 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1444 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1445
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1446 <varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1447 <term><option>--library=LIBSPEC</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1448 <term><option>-l LIBSPEC</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1449 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1450 <para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1451 Load a library using the library search path. LIBSPEC will have "lib" prepended
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1452 and ".a" appended.
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1453 </para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1454 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1455 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1456
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1457 <varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1458 <term><option>--library-path=DIR</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1459 <term><option>-L DIR</option></term>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1460 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1461 <para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1462 Add DIR to the library search path.
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1463 </para>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1464 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1465 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1466
bc2fae9438eb Updated documentation to reflect recent changes lost parents: 175 diff changeset	1467 <varlistentry>
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1468 <term><option>--debug</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1469 <term><option>-d</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1470 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1471 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1472 This option increases the debugging level. It is only useful for LWTOOLS
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1473 developers.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1474 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1475 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1476 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1477
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1478 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1479 <term><option>--help</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1480 <term><option>-?</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1481 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1482 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1483 This provides a listing of command line options and a brief description
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1484 of each.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1485 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1486 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1487 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1488
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1489 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1490 <term><option>--usage</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1491 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1492 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1493 This will display a usage summary.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1494 of each.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1495 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1496 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1497 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1498
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1499
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1500 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1501 <term><option>--version</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1502 <term><option>-V</option></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1503 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1504 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1505 This will display the version of LWLINK.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1506 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1507 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1508 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1509
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1510 </section>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1511
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1512 <section>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1513 <title>Linker Operation</title>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1514
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1515 <para>
175 f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1516
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1517 LWLINK takes one or more files in supported input formats and links them
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1518 into a single binary. Currently supported formats are the LWTOOLS object
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1519 file format and the archive format used by LWAR. While the precise method is
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1520 slightly different, linking can be conceptualized as the following steps.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1521
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1522 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1523
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1524 <orderedlist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1525 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1526 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1527 First, the linker loads a linking script. If no script is specified, it
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1528 loads a built-in default script based on the output format selected. This
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1529 script tells the linker how to lay out the various sections in the final
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1530 binary.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1531 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1532 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1533
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1534 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1535 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1536 Next, the linker reads all the input files into memory. At this time, it
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1537 flags any format errors in those files. It constructs a table of symbols
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1538 for each object at this time.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1539 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1540 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1541
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1542 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1543 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1544 The linker then proceeds with organizing the sections loaded from each file
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1545 according to the linking script. As it does so, it is able to assign addresses
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1546 to each symbol defined in each object file. At this time, the linker may
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1547 also collapse different instances of the same section name into a single
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1548 section by appending the data from each subsequent instance of the section
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1549 to the first instance of the section.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1550 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1551 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1552
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1553 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1554 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1555 Next, the linker looks through every object file for every incomplete reference.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1556 It then attempts to fully resolve that reference. If it cannot do so, it
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1557 throws an error. Once a reference is resolved, the value is placed into
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1558 the binary code at the specified section. It should be noted that an
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1559 incomplete reference can reference either a symbol internal to the object
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1560 file or an external symbol which is in the export list of another object
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1561 file.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1562 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1563 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1564
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1565 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1566 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1567 If all of the above steps are successful, the linker opens the output file
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1568 and actually constructs the binary.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1569 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1570 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1571 </orderedlist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1572
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1573 </section>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1574
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1575 <section
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1576 <title>Linking Scripts</title>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1577 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1578 A linker script is used to instruct the linker about how to assemble the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1579 various sections into a completed binary. It consists of a series of
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1580 directives which are considered in the order they are encountered.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1581 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1582 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1583 The sections will appear in the resulting binary in the order they are
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1584 specified in the script file. If a referenced section is not found, the linker will behave as though the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1585 section did exist but had a zero size, no relocations, and no exports.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1586 A section should only be referenced once. Any subsequent references will have
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1587 an undefined effect.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1588 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1589
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1590 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1591 All numbers are in linking scripts are specified in hexadecimal. All directives
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1592 are case sensitive although the hexadecimal numbers are not.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1593 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1594
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1595 <para>A section name can be specified as a "*", then any section not
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1596 already matched by the script will be matched. The "*" can be followed
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1597 by a comma and a flag to narrow the section down slightly, also.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1598 If the flag is "!bss", then any section that is not flagged as a bss section
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1599 will be matched. If the flag is "bss", then any section that is flagged as
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1600 bss will be matched.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1601 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1602
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1603 <para>The following directives are understood in a linker script.</para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1604 <variablelist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1605 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1606 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1607 <listitem><para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1608
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1609 This causes the section <parameter>name</parameter> to load at
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1610 <parameter>addr</parameter>. For the raw target, only one "load at" entry is
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1611 allowed for non-bss sections and it must be the first one. For raw targets,
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1612 it affects the addresses the linker assigns to symbols but has no other
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1613 affect on the output. bss sections may all have separate load addresses but
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1614 since they will not appear in the binary anyway, this is okay.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1615 </para><para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1616 For the decb target, each "load" entry will cause a new "block" to be
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1617 output to the binary which will contain the load address. It is legal for
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1618 sections to overlap in this manner - the linker assumes the loader will sort
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1619 everything out.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1620 </para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1621 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1622
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1623 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1624 <term>section <parameter>name</parameter></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1625 <listitem><para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1626
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1627 This will cause the section <parameter>name</parameter> to load after the previously listed
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1628 section.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1629 </para></listitem></varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1630 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1631 <term>exec <parameter>addr or sym</parameter></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1632 <listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1633 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1634 This will cause the execution address (entry point) to be the address
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1635 specified (in hex) or the specified symbol name. The symbol name must
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1636 match a symbol that is exported by one of the object files being linked.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1637 This has no effect for targets that do not encode the entry point into the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1638 resulting file. If not specified, the entry point is assumed to be address 0
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1639 which is probably not what you want. The default link scripts for targets
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1640 that support this directive automatically starts at the beginning of the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1641 first section (usually "init" or "code") that is emitted in the binary.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1642 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1643 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1644 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1645
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1646 <varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1647 <term>pad <parameter>size</parameter></term>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1648 <listitem><para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1649 This will cause the output file to be padded with NUL bytes to be exactly
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1650 <parameter>size</parameter> bytes in length. This only makes sense for a raw target.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1651 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1652 </listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1653 </varlistentry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1654 </variablelist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1655
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1656
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1657
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1658 </section>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1659
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1660 </chapter>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1661
175 f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1662 <chapter>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1663 <title>Libraries and LWAR</title>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1664
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1665 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1666 LWTOOLS also includes a tool for managing libraries. These are analogous to
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1667 the static libraries created with the "ar" tool on POSIX systems. Each library
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1668 file contains one or more object files. The linker will treat the object
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1669 files within a library as though they had been specified individually on
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1670 the command line except when resolving external references. External references
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1671 are looked up first within the object files within the library and then, if
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1672 not found, the usual lookup based on the order the files are specified on
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1673 the command line occurs.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1674 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1675
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1676 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1677 The tool for creating these libary files is called LWAR.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1678 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1679
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1680 <section>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1681 <title>Command Line Options</title>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1682 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1683 The binary for LWAR is called "lwar". Note that the binary is in lower
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1684 case. The options lwar understands are listed below. For archive manipulation
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1685 options, the first non-option argument is the name of the archive. All other
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1686 non-option arguments are the names of files to operate on.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1687 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1688
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1689 <variablelist>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1690 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1691 <term><option>--add</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1692 <term><option>-a</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1693 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1694 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1695 This option specifies that an archive is going to have files added to it.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1696 If the archive does not already exist, it is created. New files are added
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1697 to the end of the archive.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1698 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1699 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1700 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1701
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1702 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1703 <term><option>--create</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1704 <term><option>-c</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1705 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1706 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1707 This option specifies that an archive is going to be created and have files
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1708 added to it. If the archive already exists, it is truncated.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1709 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1710 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1711 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1712
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1713 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1714 <term><option>--merge</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1715 <term><option>-m</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1716 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1717 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1718 If specified, any files specified to be added to an archive will be checked
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1719 to see if they are archives themselves. If so, their constituent members are
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1720 added to the archive. This is useful for avoiding archives containing archives.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1721 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1722 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1723 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1724
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1725 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1726 <term><option>--list</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1727 <term><option>-l</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1728 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1729 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1730 This will display a list of the files contained in the archive.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1731 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1732 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1733 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1734
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1735 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1736 <term><option>--debug</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1737 <term><option>-d</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1738 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1739 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1740 This option increases the debugging level. It is only useful for LWTOOLS
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1741 developers.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1742 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1743 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1744 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1745
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1746 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1747 <term><option>--help</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1748 <term><option>-?</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1749 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1750 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1751 This provides a listing of command line options and a brief description
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1752 of each.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1753 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1754 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1755 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1756
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1757 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1758 <term><option>--usage</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1759 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1760 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1761 This will display a usage summary.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1762 of each.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1763 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1764 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1765 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1766
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1767
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1768 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1769 <term><option>--version</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1770 <term><option>-V</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1771 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1772 <para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1773 This will display the version of LWLINK.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1774 of each.
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1775 </para>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1776 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1777 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1778
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1779 </section>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1780
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1781 </chapter>
f8ec28ace0c6 Updated docs to reflect recent changes lost parents: 167 diff changeset	1782
109 f21a5593a661 Updated docs lost parents: diff changeset	1783 <chapter id="objchap">
f21a5593a661 Updated docs lost parents: diff changeset	1784 <title>Object Files</title>
145 afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1785 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1786 LWTOOLS uses a proprietary object file format. It is proprietary in the sense
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1787 that it is specific to LWTOOLS, not that it is a hidden format. It would be
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1788 hard to keep it hidden in an open source tool chain anyway. This chapter
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1789 documents the object file format.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release lost parents: 109 diff changeset	1790 </para>
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1791
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1792 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1793 An object file consists of a series of sections each of which contains a
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1794 list of exported symbols, a list of incomplete references, and a list of
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1795 "local" symbols which may be used in calculating incomplete references. Each
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1796 section will obviously also contain the object code.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1797 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1798
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1799 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1800 Exported symbols must be completely resolved to an address within the
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1801 section it is exported from. That is, an exported symbol must be a constant
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1802 rather than defined in terms of other symbols.</para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1803
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1804 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1805 Each object file starts with a magic number and version number. The magic
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1806 number is the string "LWOBJ16" for this 16 bit object file format. The only
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1807 defined version number is currently 0. Thus, the first 8 bytes of the object
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1808 file are <code>4C574F424A313600</code>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1809 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1810
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1811 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1812 Each section has the following items in order:
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1813 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1814
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1815 <itemizedlist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1816 <listitem><para>section name</para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1817 <listitem><para>flags</para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1818 <listitem><para>list of local symbols (and addresses within the section)</para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1819 <listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1820 <listitem><para>list of incomplete references along with the expressions to calculate them</para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1821 <listitem><para>the actual object code (for non-BSS sections)</para></listitem>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1822 </itemizedlist>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1823
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1824 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1825 The section starts with the name of the section with a NUL termination
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1826 followed by a series of flag bytes terminated by NUL. There are only two
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1827 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1828 indicates the section is a BSS section. For a BSS section, no actual
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1829 code is included in the object file.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1830 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1831
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1832 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1833 Either a NULL section name or end of file indicate the presence of no more
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1834 sections.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1835 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1836
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1837 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1838 Each entry in the exported and local symbols table consists of the symbol
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1839 (NUL terminated) followed by two bytes which contain the value in big endian
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1840 order. The end of a symbol table is indicated by a NULL symbol name.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1841 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1842
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1843 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1844 Each entry in the incomplete references table consists of an expression
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1845 followed by a 16 bit offset where the reference goes. Expressions are
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1846 defined as a series of terms up to an "end of expression" term. Each term
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1847 consists of a single byte which identifies the type of term (see below)
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1848 followed by any data required by the term. Then end of the list is flagged
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1849 by a NULL expression (only an end of expression term).
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1850 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1851
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1852 <table frame="all"><title>Object File Term Types</title>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1853 <tgroup cols="2">
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1854 <thead>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1855 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1856 <entry>TERMTYPE</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1857 <entry>Meaning</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1858 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1859 </thead>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1860 <tbody>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1861 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1862 <entry>00</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1863 <entry>end of expression</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1864 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1865
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1866 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1867 <entry>01</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1868 <entry>integer (16 bit in big endian order follows)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1869 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1870 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1871 <entry>02</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1872 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1873 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1874
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1875 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1876 <entry>03</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1877 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1878 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1879
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1880 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1881 <entry>04</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1882 <entry>operator (1 byte operator number)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1883 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1884 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1885 <entry>05</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1886 <entry>section base address reference</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1887 </row>
232 1009f302ac11 Documented the "Flags" term for object files lost parents: 231 diff changeset	1888
1009f302ac11 Documented the "Flags" term for object files lost parents: 231 diff changeset	1889 <row>
1009f302ac11 Documented the "Flags" term for object files lost parents: 231 diff changeset	1890 <entry>FF</entry>
1009f302ac11 Documented the "Flags" term for object files lost parents: 231 diff changeset	1891 <entry>This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. There is currently only one flag defined. Flag 01 indicates an 8 bit relocation.</entry>
1009f302ac11 Documented the "Flags" term for object files lost parents: 231 diff changeset	1892 </row>
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1893 </tbody>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1894 </tgroup>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1895 </table>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1896
232 1009f302ac11 Documented the "Flags" term for object files lost parents: 231 diff changeset	1897
150 f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1898 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1899 External references are resolved using other object files while local
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1900 references are resolved using the local symbol table(s) from this file. This
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1901 allows local symbols that are not exported to have the same names as
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1902 exported symbols or external references.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1903 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1904
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1905 <table frame="all"><title>Object File Operator Numbers</title>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1906 <tgroup cols="2">
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1907 <thead>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1908 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1909 <entry>Number</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1910 <entry>Operator</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1911 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1912 </thead>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1913 <tbody>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1914 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1915 <entry>01</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1916 <entry>addition (+)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1917 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1918 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1919 <entry>02</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1920 <entry>subtraction (-)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1921 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1922 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1923 <entry>03</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1924 <entry>multiplication (*)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1925 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1926 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1927 <entry>04</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1928 <entry>division (/)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1929 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1930 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1931 <entry>05</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1932 <entry>modulus (%)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1933 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1934 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1935 <entry>06</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1936 <entry>integer division (\) (same as division)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1937 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1938
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1939 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1940 <entry>07</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1941 <entry>bitwise and</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1942 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1943
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1944 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1945 <entry>08</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1946 <entry>bitwise or</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1947 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1948
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1949 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1950 <entry>09</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1951 <entry>bitwise xor</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1952 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1953
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1954 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1955 <entry>0A</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1956 <entry>boolean and</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1957 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1958
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1959 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1960 <entry>0B</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1961 <entry>boolean or</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1962 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1963
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1964 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1965 <entry>0C</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1966 <entry>unary negation, 2's complement (-)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1967 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1968
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1969 <row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1970 <entry>0D</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1971 <entry>unary 1's complement (^)</entry>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1972 </row>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1973 </tbody>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1974 </tgroup>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1975 </table>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1976
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1977 <para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1978 An expression is represented in a postfix manner with both operands for
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1979 binary operators preceding the operator and the single operand for unary
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1980 operators preceding the operator.
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1981 </para>
f0881c115010 More major documentation upgrades lost parents: 147 diff changeset	1982
109 f21a5593a661 Updated docs lost parents: diff changeset	1983 </chapter>
f21a5593a661 Updated docs lost parents: diff changeset	1984 </book>
f21a5593a661 Updated docs lost parents: diff changeset	1985

Mercurial > hg-old > index.cgi

annotate doc/manual.docbook.sgml @ 276:23034db7dd8a 2.5