annotate doc/manual.docbook.sgml @ 159:71561c12b20b

Updated docs to reflect new cescapes pragma and discuss implicit assumption of the bss section flag for sections named bss and .bss
author lost
date Sat, 31 Jan 2009 06:32:27 +0000
parents f0881c115010
children 751b99efb1fc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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>
f21a5593a661 Updated docs
lost
parents:
diff changeset
95 <title>Object Files</title>
f21a5593a661 Updated docs
lost
parents:
diff changeset
96 <para>LWASM supports generating a proprietary object file format which is
f21a5593a661 Updated docs
lost
parents:
diff changeset
97 described in <xref linkend="objchap">. LWLINK is then used to link these
f21a5593a661 Updated docs
lost
parents:
diff changeset
98 object files into a final binary in any of LWLINK's supported binary
f21a5593a661 Updated docs
lost
parents:
diff changeset
99 formats.</para>
f21a5593a661 Updated docs
lost
parents:
diff changeset
100
f21a5593a661 Updated docs
lost
parents:
diff changeset
101 <para>Object files are very flexible in that they allow references that are not
f21a5593a661 Updated docs
lost
parents:
diff changeset
102 known at assembly time to be resolved at link time. However, because the
f21a5593a661 Updated docs
lost
parents:
diff changeset
103 addresses of such references are not known, there is no way for the assembler
f21a5593a661 Updated docs
lost
parents:
diff changeset
104 has to use sixteen bit addressing modes for these references. The linker
f21a5593a661 Updated docs
lost
parents:
diff changeset
105 will always use sixteen bits when resolving a reference which means any
f21a5593a661 Updated docs
lost
parents:
diff changeset
106 instruction that requires an eight bit operand cannot use external references.
f21a5593a661 Updated docs
lost
parents:
diff changeset
107 </para>
f21a5593a661 Updated docs
lost
parents:
diff changeset
108
f21a5593a661 Updated docs
lost
parents:
diff changeset
109 <para>Object files also support the concept of sections which are not valid
f21a5593a661 Updated docs
lost
parents:
diff changeset
110 for other output types. This allows related code from each object file
f21a5593a661 Updated docs
lost
parents:
diff changeset
111 linked to be collapsed together in the final binary.</para>
f21a5593a661 Updated docs
lost
parents:
diff changeset
112
f21a5593a661 Updated docs
lost
parents:
diff changeset
113 </section>
f21a5593a661 Updated docs
lost
parents:
diff changeset
114
f21a5593a661 Updated docs
lost
parents:
diff changeset
115 </chapter>
f21a5593a661 Updated docs
lost
parents:
diff changeset
116
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
117 <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
118 <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
119 <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
120 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
121 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
122 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
123 </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
124
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
125 <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
126 <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
127 <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
128 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
129 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
130 </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
131
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
132 <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
133 <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
134 <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
135 <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
136 <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
137 <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
138 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
139 </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
140 </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
141 </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
142
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
143 <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
144 <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
145 <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
146 <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
147 <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
148 Select the output format. Valid values are <option>obj</option> for the object
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
149 file target, <option>decb</option> for the DECB LOADM format, and <option>raw</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
150 for a raw binary.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
151 </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
152 </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
153 </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
154
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
155 <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
156 <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
157 <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
158 <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
159 <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
160 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
161 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
162 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
163 </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
164 </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
165 </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
166
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
167 <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
168 <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
169 <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
170 <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
171 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
172 </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
173 </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
174 </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
175
afe30454382f Made development 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 <varlistentry>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
177 <term><option>--output=FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
178 <term><option>-o FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
179 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
180 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
181 This option specifies the name of the output file. If not specified, the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
182 default is <option>a.out</option>.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
183 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
184 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
185 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
186
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
187 <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
188 <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
189 <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
190 <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
191 <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
192 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
193 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
194 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
195 </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
196 </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
197 </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
198
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
199 <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
200 <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
201 <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
202 <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
203 <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
204 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
205 </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
206 </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
207 </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
208
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
209 <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
210 <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
211 <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
212 <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
213 <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
214 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
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 </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
217 </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
218
afe30454382f Made development 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 <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
221 <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
222 <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
223 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
224 </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
225 </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
226 </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
227
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
228 <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
229 <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
230 <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
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 <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
233 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
234 </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
235 </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
236 </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
237
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
238 <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
239 <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
240 <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
241 <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
242 <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
243 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
244 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
245 </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
246 </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
247 </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
248
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
249 </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
250
afe30454382f Made development 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 </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
252
afe30454382f Made development 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 <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
254 <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
255 <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
256 LWASM supports all documented MC6809 instructions as defined by Motorola.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
257 It also supports all known HD6309 instructions. There is some variation,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
258 however, in the pneumonics used for the block transfer instructions. 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
259 uses TFM for all four of them as do several other assemblers. Others, such
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
260 as CCASM, use four separate opcodes for it (compare: copy+, copy-, implode,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
261 and explode). There are advantages to both methods. However, it seems like
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
262 TFM has the most traction and thus, this is what LWASM supports. Support
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
263 for such variations may be added in the future.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
264 </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
265
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
266 <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
267 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
268 hash sign ("#") for immediate mode, the less than sign ("&lt;") 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
269 eight bit modes, and the greater than sign ("&gt;") 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
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
afe30454382f Made development 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 </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
273
afe30454382f Made development 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 <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
275 <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
276
afe30454382f Made development 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 <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
278 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
279 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
280 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
281 </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
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 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
284 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
285 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
286 <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
287 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
288 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
289 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
290 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
291 </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
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 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
294 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
295 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
296 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
297 </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
298
afe30454382f Made development 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 <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
300 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
301 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
302 </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
303
afe30454382f Made development 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 <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
305 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
306 </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
307
afe30454382f Made development 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 </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
309
afe30454382f Made development 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 <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
311 <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
312
afe30454382f Made development 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 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
315 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
316 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
317 </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
318
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
319 <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
320 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
321 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
322 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
323 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
324 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
325 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
326 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
327 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
328 </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
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>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
334 <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
335 Numbers can be expressed in binary, octal, decimal, or hexadecimal.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
336 Binary numbers may be prefixed with a "%" symbol or suffixed 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
337 "b" or "B". Octal numbers may be prefixed with "@" or suffixed 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
338 "Q", "q", "O", or "o". Hexadecimal numbers may be prefixed with "$" 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
339 suffixed with "H". No prefix or suffix is required for decimal numbers but
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
340 they can be prefixed with "&amp;" if desired. Any constant which begins 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
341 a letter must be expressed with the correct prefix base identifier or 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
342 prefixed with a 0. Thus hexadecimal FF would have to be written either 0FFH
afe30454382f Made development 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 or $FF. Numbers are not 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
344 </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
345
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
346 <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
347 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
348 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
349
afe30454382f Made development 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 <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
351 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
352 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
353
afe30454382f Made development 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 <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
355 LWASM supports the following basic binary operators: +, -, *, /, 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
356 These represent addition, subtraction, multiplication, division, and modulus.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
357 It also supports unary negation and unary 1's complement (- and ^ respectively).
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
358 For completeness, a unary positive (+) is supported though it is a no-op.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
359 </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
360
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
361 <para>Operator precedence follows the usual rules. multiplication, division,
afe30454382f Made development 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 and modulus take precedence over addition and subtraction. Unary operators
afe30454382f Made development 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 take precedence over binary operators. To force a specific order of evaluation,
afe30454382f Made development 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 parentheses can be used in the usual manner.
afe30454382f Made development 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 </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
366 </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
367
afe30454382f Made development 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 <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
369 <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
370 <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
371 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
372 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
373 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
374 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
375 </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
afe30454382f Made development 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 <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
378 <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
379 <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
380 <varlistentry><term>FCB <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
381 <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
382 <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
383 </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
384 </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
385
afe30454382f Made development 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 <varlistentry><term>FDB <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
387 <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
388 <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
389 </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
390 </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
391
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
392 <varlistentry><term>FQB <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
393 <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
394 <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
395 </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
396 </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
397
afe30454382f Made development 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 <varlistentry><term>FCC <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
399 <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
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 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
402 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
403 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
404 </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
405 </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
406 </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
407
afe30454382f Made development 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 <varlistentry><term>FCN <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
409 <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
410 <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
411 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
412 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
413 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
414 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
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 </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
417 </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
418
afe30454382f Made development 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 <varlistentry><term>FCS <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
420 <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
421 <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
422 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
423 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
424 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
425 </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
426 </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
427 </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
428
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
429 <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
430 <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
431 <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
432 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
433 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
434 </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
435 </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
436 </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
437
afe30454382f Made development 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 <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
439 <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
440 <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
441 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
442 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
443 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
444 </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
445 </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
446 </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
447
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
448 <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
449 <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
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 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
452 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
453 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
454 </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 </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
456 </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
457
afe30454382f Made development 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 <varlistentry><term>RMB <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
459 <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
460 <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
461 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
462 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
463 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
464 </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
465 </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
466 </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
467
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
468 <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
469 <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
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 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
472 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
473 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
474 </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
475 </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
476 </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
477
afe30454382f Made development 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 <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
479 <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
480 <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
481 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
482 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
483 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
484 </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
485 </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
486 </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
487 </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
488
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
489 </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
490
afe30454382f Made development 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 <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
492 <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
493 <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
494 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
495
afe30454382f Made development 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 <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
497 <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
498 <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
499 <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
500 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
501 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
502 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
503 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
504 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
505 </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
506 </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
507 </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
508
afe30454382f Made development 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 <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
510 <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
511 <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
512 <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
513 <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
514 </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
515 </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
516
afe30454382f Made development 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 <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
518 <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
519 <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
520 <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
521 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
522 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
523 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
524 </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
525 </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
526
afe30454382f Made development 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 <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
528 <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
529 <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
530 <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
531 <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
532 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
533 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
534 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
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 <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
537 </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
538 </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
539 </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
540
afe30454382f Made development 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 <term>ALIGN <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
543 <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
544 <para>Force the current assembly address to be a multiple of <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
545 A series of NUL bytes is output to force the alignment, if required. 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
546 alignment value must be fully resolved on the first pass because it affects
afe30454382f Made development 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 the addresses of subsquent instructions.</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
548 <para>This directive is not suitable for inclusion in the middle of actual
afe30454382f Made development 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 code. It is intended to appear where the bytes output will not be executed.
afe30454382f Made development 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 </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
551 </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
552 </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
553
afe30454382f Made development 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 </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
555
afe30454382f Made development 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 </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
557
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
558 <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
559 <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
560 <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
561 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
562 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
563 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
564 </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
565 <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
566 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
567 </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
568 <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
569 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
570 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
571 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
572
afe30454382f Made development 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 <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
574 <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
575 <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
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 <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
578 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
579 </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
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 </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
582
afe30454382f Made development 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 <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
584 <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
585 <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
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 <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
588 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
589 </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
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 </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
592
afe30454382f Made development 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 <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
594 <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
595 <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
596 <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
597 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
598 </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
599 </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
600 </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
601
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
602 <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
603 <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
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>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
606 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
607 </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
608 </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
609 </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
610
afe30454382f Made development 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 <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
613 <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
614 <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
615 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
616 </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
617 </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
618 </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
619
afe30454382f Made development 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 <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
621 <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
622 <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
623 <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
624 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
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 </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
627 </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
628
afe30454382f Made development 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 <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
630 <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
631 <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
632 <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
633 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
634 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
635 </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
636 </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
637 </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
638
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
639 <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
640 <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
641 <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
642 <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
643 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
644 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
645 </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
646 </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
647 </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
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 <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
650 <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
651 <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
652 <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 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
654 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
655 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
656 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
657 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
658 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
659 </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
660 </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
661
afe30454382f Made development 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 <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
663 <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
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 <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
666 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
667 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
668 </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
669 </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
670 </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
671
afe30454382f Made development 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 </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
673 </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
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 <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
676 <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
677
afe30454382f Made development 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>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
679 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
680
afe30454382f Made development 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 <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
682
afe30454382f Made development 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 <term>INCLUDE <parameter>filename</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
685 <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
686 <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
687 Include the contents of <parameter>filename</parameter> at this point 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
688 the assembly as though it were a part of the file currently being processed.
afe30454382f Made development 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 Note that whitespace cannot appear in the name of 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
690 </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
691 </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
692 </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
693
afe30454382f Made development 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 <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
695 <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
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 <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
698 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
699 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
700 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
701 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
702 </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
703 </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
704 </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
705
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
706 <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
707 <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
708 <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
709 <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
710 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
711 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
712 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
713 </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
714 </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
715 </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
716
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
717 </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
718 </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
719
afe30454382f Made development 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 </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
721
afe30454382f Made development 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 <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
723 <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
724 <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
725 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
726 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
727 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
728 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
729 </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
730 <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
731 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
732 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
733 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
734 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
735 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
736 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
737 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
738 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
739 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
740 </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
741 <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
742 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
743 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
744 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
745 </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
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 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
748 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
749 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
750 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
751
afe30454382f Made development 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 <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
753 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
754 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
755 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
756 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
757 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
758 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
759 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
760 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
761 </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
762 <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
763 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
764 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
765 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
766 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
767 </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
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 <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
770 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
771 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
772 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
773 </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
774
afe30454382f Made development 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 <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
776
afe30454382f Made development 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 <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
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><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
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>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
782 <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
783 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
784 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
785 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
786 </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
787 </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
788 </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
789
afe30454382f Made development 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 <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
791 <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
792 <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
793 <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
794 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
795 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
796 </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
797 </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
798 </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
799
afe30454382f Made development 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 </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
801
afe30454382f Made development 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 <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
803 <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
804 <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
805 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
806 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
807 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
808 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
809 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
810 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
811 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
812 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
813 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
814 </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
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 <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
817 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
818 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
819 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
820 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
821 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
822 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
823 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
824 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
825 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
826 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
827 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
828 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
829 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
830 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
831 </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
832
afe30454382f Made development 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 <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
834 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
835 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
836 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
837 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
838 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
839 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
840 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
841 </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
842
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
843 <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
844 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
845 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
846 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
847 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
848 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
849 </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
850
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
851 <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
852 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
853 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
854 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
855 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
856 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
857 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
858 </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
859
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
860 <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
861 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
862 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
863 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
864 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
865 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
866 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
867 </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
868
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
869 <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
870 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
871 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
872 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
873 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
874 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
875 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
876 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
877 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
878 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
879 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
880 </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
881
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
882 <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
883
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
884 <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
885 <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
886 <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
887 <term>SECT <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
888 <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
889 <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
890 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
891 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
892 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
893 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
894 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
895 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
896 </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
897 <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
898 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
899 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
900 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
901 <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
902 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
903 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
904 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
905 </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
906 <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
907 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
908 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
909 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
910 </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
911 </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
912 </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
913
afe30454382f Made development 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 <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
915 <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
916 <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
917 <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
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 <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
920 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
921 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
922 </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
923 </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
924
afe30454382f Made development 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 <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
926 <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
927 <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
928 <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
929 <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
930 <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
931 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
932 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
933 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
934 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
935 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
936 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
937 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
938 </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
939 </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
940 </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
941
afe30454382f Made development 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 <term><parameter>sym</parameter> EXPORT</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
944 <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
945 <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
946 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
947 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
948 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
949 </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
950 </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
951 </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
952
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
953 </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
954
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
955 </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
956
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
957 <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
958 <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
959 <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
960 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
961 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
962 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
963 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
964 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
965 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
966 </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
967
afe30454382f Made development 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 <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
969 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
970 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
971 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
972 </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
973
afe30454382f Made development 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 <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
975 <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
976 <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
977 <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
978 <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
979 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
980 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
981 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
982 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
983 </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
984 </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
985 </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
986
afe30454382f Made development 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 <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
988 <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
989 <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
990 <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
991 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
992 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
993 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
994 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
995 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
996 </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
997 </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
998 </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
999 </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
1000
afe30454382f Made development 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 <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
1002 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
1003 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
1004 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
1005 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
1006
afe30454382f Made development 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 <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
1008
afe30454382f Made development 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 <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
1010 <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
1011 <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
1012 <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
1013 <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
1014 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
1015 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
1016 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
1017 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
1018 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
1019 </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
1020 </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
1021 </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
1022
afe30454382f Made development 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 <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
1024 <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
1025 <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
1026 <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
1027 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
1028 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
1029 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
1030 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
1031 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
1032 </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
1033 </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
1034 </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
1035
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
1036 <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
1037 <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
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 <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
1040 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
1041 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
1042 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
1043 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
1044 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
1045 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
1046 </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
1047 <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
1048 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
1049 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
1050 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
1051 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
1052 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
1053 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
1054 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
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 <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
1057 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
1058 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
1059 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
1060 </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
1061 </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
1062 </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
1063 </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
1064
afe30454382f Made development 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 </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
1066
afe30454382f Made development 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 </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
1068
afe30454382f Made development 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 <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
1070 <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
1071 <para>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1072 The LWTOOLS linker is called LWLINK. This chapter documents the various features
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1073 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
1074 </para>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1075
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1076 <section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1077 <title>Command Line Options</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1078 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1079 The binary for LWLINK is called "lwlink". Note that the binary is in lower
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1080 case. lwlink takes the following command line arguments.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1081 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1082 <variablelist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1083 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1084 <term><option>--decb</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1085 <term><option>-b</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1086 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1087 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1088 Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1089 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1090 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1091 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1092
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1093 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1094 <term><option>--output=FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1095 <term><option>-o FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1096 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1097 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1098 This option specifies the name of the output file. If not specified, the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1099 default is <option>a.out</option>.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1100 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1101 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1102 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1103
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1104 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1105 <term><option>--format=TYPE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1106 <term><option>-f TYPE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1107 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1108 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1109 This option specifies the output format. Valid values are <option>decb</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1110 and <option>raw</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1111 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1112 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1113 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1114
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1115 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1116 <term><option>--raw</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1117 <term><option>-r</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1118 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1119 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1120 This option specifies the raw output format.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1121 It is equivalent to <option>--format=raw</option>.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1122 and <option>raw</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1123 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1124 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1125 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1126
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1127 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1128 <term><option>--script=FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1129 <term><option>-s</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1130 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1131 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1132 This option allows specifying a linking script to override the linker's
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1133 built in defaults.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1134 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1135 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1136 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1137
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1138 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1139 <term><option>--debug</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1140 <term><option>-d</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1141 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1142 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1143 This option increases the debugging level. It is only useful for LWTOOLS
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1144 developers.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1145 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1146 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1147 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1148
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1149 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1150 <term><option>--help</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1151 <term><option>-?</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1152 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1153 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1154 This provides a listing of command line options and a brief description
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1155 of each.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1156 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1157 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1158 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1159
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1160 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1161 <term><option>--usage</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1162 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1163 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1164 This will display a usage summary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1165 of each.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1166 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1167 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1168 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1169
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1170
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1171 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1172 <term><option>--version</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1173 <term><option>-V</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1174 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1175 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1176 This will display the version of LWLINK.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1177 of each.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1178 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1179 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1180 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1181
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1182 </section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1183
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1184 <section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1185 <title>Linker Operation</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1186
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1187 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1188 LWLINK takes one or more files in the LWTOOLS object file format and links
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1189 them into a single binary. While the precise method is slightly different,
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1190 linking can be conceptualized as the following steps.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1191 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1192
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1193 <orderedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1194 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1195 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1196 First, the linker loads a linking script. If no script is specified, it
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1197 loads a built-in default script based on the output format selected. This
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1198 script tells the linker how to lay out the various sections in the final
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1199 binary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1200 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1201 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1202
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1203 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1204 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1205 Next, the linker reads all the input files into memory. At this time, it
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1206 flags any format errors in those files. It constructs a table of symbols
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1207 for each object at this time.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1208 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1209 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1210
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1211 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1212 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1213 The linker then proceeds with organizing the sections loaded from each file
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1214 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
1215 to each symbol defined in each object file. At this time, the linker may
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1216 also collapse different instances of the same section name into a single
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1217 section by appending the data from each subsequent instance of the section
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1218 to the first instance of the section.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1219 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1220 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1221
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1222 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1223 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1224 Next, the linker looks through every object file for every incomplete reference.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1225 It then attempts to fully resolve that reference. If it cannot do so, it
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1226 throws an error. Once a reference is resolved, the value is placed into
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1227 the binary code at the specified section. It should be noted that an
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1228 incomplete reference can reference either a symbol internal to the object
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1229 file or an external symbol which is in the export list of another object
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1230 file.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1231 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1232 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1233
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1234 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1235 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1236 If all of the above steps are successful, the linker opens the output file
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1237 and actually constructs the binary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1238 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1239 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1240 </orderedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1241
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1242 </section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1243
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1244 <section
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1245 <title>Linking Scripts</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1246 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1247 A linker script is used to instruct the linker about how to assemble the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1248 various sections into a completed binary. It consists of a series of
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1249 directives which are considered in the order they are encountered.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1250 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1251 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1252 The sections will appear in the resulting binary in the order they are
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1253 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
1254 section did exist but had a zero size, no relocations, and no exports.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1255 A section should only be referenced once. Any subsequent references will have
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1256 an undefined effect.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1257 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1258
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1259 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1260 All numbers are in linking scripts are specified in hexadecimal. All directives
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1261 are case sensitive although the hexadecimal numbers are not.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1262 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1263
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1264 <para>A section name can be specified as a "*", then any section not
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1265 already matched by the script will be matched. The "*" can be followed
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1266 by a comma and a flag to narrow the section down slightly, also.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1267 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
1268 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
1269 bss will be matched.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1270 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1271
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1272 <para>The following directives are understood in a linker script.</para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1273 <variablelist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1274 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1275 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1276 <listitem><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1277
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1278 This causes the section <parameter>name</parameter> to load at
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1279 <parameter>addr</parameter>. For the raw target, only one "load at" entry is
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1280 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
1281 it affects the addresses the linker assigns to symbols but has no other
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1282 affect on the output. bss sections may all have separate load addresses but
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1283 since they will not appear in the binary anyway, this is okay.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1284 </para><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1285 For the decb target, each "load" entry will cause a new "block" to be
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1286 output to the binary which will contain the load address. It is legal for
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1287 sections to overlap in this manner - the linker assumes the loader will sort
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1288 everything out.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1289 </para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1290 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1291
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1292 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1293 <term>section <parameter>name</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1294 <listitem><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1295
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1296 This will cause the section <parameter>name</parameter> to load after the previously listed
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1297 section.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1298 </para></listitem></varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1299 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1300 <term>exec <parameter>addr or sym</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1301 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1302 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1303 This will cause the execution address (entry point) to be the address
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1304 specified (in hex) or the specified symbol name. The symbol name must
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1305 match a symbol that is exported by one of the object files being linked.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1306 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
1307 resulting file. If not specified, the entry point is assumed to be address 0
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1308 which is probably not what you want. The default link scripts for targets
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1309 that support this directive automatically starts at the beginning of the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1310 first section (usually "init" or "code") that is emitted in the binary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1311 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1312 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1313 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1314
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1315 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1316 <term>pad <parameter>size</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1317 <listitem><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1318 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
1319 <parameter>size</parameter> bytes in length. This only makes sense for a raw target.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1320 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1321 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1322 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1323 </variablelist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1324
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1325
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1326
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1327 </section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1328
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
1329 </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
1330
109
f21a5593a661 Updated docs
lost
parents:
diff changeset
1331 <chapter id="objchap">
f21a5593a661 Updated docs
lost
parents:
diff changeset
1332 <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
1333 <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
1334 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
1335 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
1336 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
1337 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
1338 </para>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1339
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1340 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1341 An object file consists of a series of sections each of which contains a
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1342 list of exported symbols, a list of incomplete references, and a list of
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1343 "local" symbols which may be used in calculating incomplete references. Each
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1344 section will obviously also contain the object code.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1345 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1346
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1347 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1348 Exported symbols must be completely resolved to an address within the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1349 section it is exported from. That is, an exported symbol must be a constant
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1350 rather than defined in terms of other symbols.</para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1351
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1352 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1353 Each object file starts with a magic number and version number. The magic
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1354 number is the string "LWOBJ16" for this 16 bit object file format. The only
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1355 defined version number is currently 0. Thus, the first 8 bytes of the object
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1356 file are <code>4C574F424A313600</code>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1357 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1358
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1359 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1360 Each section has the following items in order:
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1361 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1362
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1363 <itemizedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1364 <listitem><para>section name</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1365 <listitem><para>flags</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1366 <listitem><para>list of local symbols (and addresses within the section)</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1367 <listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1368 <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
1369 <listitem><para>the actual object code (for non-BSS sections)</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1370 </itemizedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1371
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1372 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1373 The section starts with the name of the section with a NUL termination
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1374 followed by a series of flag bytes terminated by NUL. There are only two
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1375 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
1376 indicates the section is a BSS section. For a BSS section, no actual
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1377 code is included in the object file.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1378 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1379
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1380 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1381 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
1382 sections.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1383 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1384
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1385 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1386 Each entry in the exported and local symbols table consists of the symbol
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1387 (NUL terminated) followed by two bytes which contain the value in big endian
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1388 order. The end of a symbol table is indicated by a NULL symbol name.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1389 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1390
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1391 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1392 Each entry in the incomplete references table consists of an expression
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1393 followed by a 16 bit offset where the reference goes. Expressions are
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1394 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
1395 consists of a single byte which identifies the type of term (see below)
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1396 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
1397 by a NULL expression (only an end of expression term).
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1398 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1399
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1400 <table frame="all"><title>Object File Term Types</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1401 <tgroup cols="2">
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1402 <thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1403 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1404 <entry>TERMTYPE</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1405 <entry>Meaning</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1406 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1407 </thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1408 <tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1409 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1410 <entry>00</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1411 <entry>end of expression</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1412 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1413
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1414 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1415 <entry>01</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1416 <entry>integer (16 bit in big endian order follows)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1417 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1418 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1419 <entry>02</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1420 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1421 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1422
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1423 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1424 <entry>03</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1425 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1426 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1427
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1428 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1429 <entry>04</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1430 <entry>operator (1 byte operator number)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1431 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1432 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1433 <entry>05</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1434 <entry>section base address reference</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1435 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1436 </tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1437 </tgroup>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1438 </table>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1439
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1440 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1441 External references are resolved using other object files while local
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1442 references are resolved using the local symbol table(s) from this file. This
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1443 allows local symbols that are not exported to have the same names as
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1444 exported symbols or external references.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1445 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1446
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1447 <table frame="all"><title>Object File Operator Numbers</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1448 <tgroup cols="2">
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1449 <thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1450 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1451 <entry>Number</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1452 <entry>Operator</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1453 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1454 </thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1455 <tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1456 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1457 <entry>01</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1458 <entry>addition (+)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1459 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1460 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1461 <entry>02</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1462 <entry>subtraction (-)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1463 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1464 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1465 <entry>03</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1466 <entry>multiplication (*)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1467 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1468 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1469 <entry>04</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1470 <entry>division (/)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1471 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1472 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1473 <entry>05</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1474 <entry>modulus (%)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1475 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1476 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1477 <entry>06</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1478 <entry>integer division (\) (same as division)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1479 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1480
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1481 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1482 <entry>07</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1483 <entry>bitwise and</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1484 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1485
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1486 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1487 <entry>08</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1488 <entry>bitwise or</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1489 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1490
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1491 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1492 <entry>09</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1493 <entry>bitwise xor</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1494 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1495
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1496 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1497 <entry>0A</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1498 <entry>boolean and</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1499 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1500
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1501 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1502 <entry>0B</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1503 <entry>boolean or</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1504 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1505
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1506 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1507 <entry>0C</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1508 <entry>unary negation, 2's complement (-)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1509 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1510
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1511 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1512 <entry>0D</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1513 <entry>unary 1's complement (^)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1514 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1515 </tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1516 </tgroup>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1517 </table>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1518
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1519 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1520 An expression is represented in a postfix manner with both operands for
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1521 binary operators preceding the operator and the single operand for unary
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1522 operators preceding the operator.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1523 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1524
109
f21a5593a661 Updated docs
lost
parents:
diff changeset
1525 </chapter>
f21a5593a661 Updated docs
lost
parents:
diff changeset
1526 </book>
f21a5593a661 Updated docs
lost
parents:
diff changeset
1527