Mercurial > hg-old > index.cgi

annotate doc/manual.docbook.sgml @ 265:68fbca173508 2.6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added generated files for release
author lost
date Tue, 22 Dec 2009 05:31:23 +0000
parents 6e2d03188d24
children
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>
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
95 <title>OS9 Modules</title>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
96 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
97
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
98 Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
99 basically the same as for other assemblers. A module starts with the MOD
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
100 directive and ends with the EMOD directive. The OS9 directive is provided
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
101 as a shortcut for writing system calls.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
102
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
103 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
104
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
105 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
106
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
107 LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
108 that the common practice of using "ifp1" around the inclusion of the OS9Defs
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
109 file is discouraged as it is pointless and can lead to unintentional
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
110 problems and phasing errors. Because LWASM reads each file exactly once,
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
111 there is no benefit to restricting the inclusion to the first assembly pass.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
112
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
113 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
114
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
115 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
116
240
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
117 It is also critical to understand that unlike many OS9 assemblers, LWASM
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
118 does NOT maintain a separate data address counter. Thus, you must define
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
119 all your data offsets and so on outside of the mod/emod segment. It is,
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
120 therefore, likely that source code targeted at other assemblers will require
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
121 edits to build correctly.
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
122
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
123 </para>
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
124
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
125 <para>
b43e3e23583c Added not about likely incompatibilities with source code from other assemblers when using the OS9 module target
lost
parents: 237
diff changeset
126
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
127 LWLINK does not, yet, have the ability to create OS9 modules from object
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
128 files.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
129
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
130 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
131 </section>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
132
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
133 <section>
109
f21a5593a661 Updated docs
lost
parents:
diff changeset
134 <title>Object Files</title>
f21a5593a661 Updated docs
lost
parents:
diff changeset
135 <para>LWASM supports generating a proprietary object file format which is
f21a5593a661 Updated docs
lost
parents:
diff changeset
136 described in <xref linkend="objchap">. LWLINK is then used to link these
f21a5593a661 Updated docs
lost
parents:
diff changeset
137 object files into a final binary in any of LWLINK's supported binary
f21a5593a661 Updated docs
lost
parents:
diff changeset
138 formats.</para>
f21a5593a661 Updated docs
lost
parents:
diff changeset
139
f21a5593a661 Updated docs
lost
parents:
diff changeset
140 <para>Object files also support the concept of sections which are not valid
f21a5593a661 Updated docs
lost
parents:
diff changeset
141 for other output types. This allows related code from each object file
f21a5593a661 Updated docs
lost
parents:
diff changeset
142 linked to be collapsed together in the final binary.</para>
f21a5593a661 Updated docs
lost
parents:
diff changeset
143
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
144 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
145 Object files are very flexible in that they allow references that are not
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
146 known at assembly time to be resolved at link time. However, because the
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
147 addresses of such references are not known at assembly time, there is no way
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
148 for the assembler to deduce that an eight bit addressing mode is possible.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
149 That means the assember will default to using sixteen bit addressing
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
150 whenever an external or cross-section reference is used.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
151 </para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
152
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
153 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
154 As of LWASM 2.4, it is possible to force direct page addressing for an
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
155 external reference. Care must be taken to ensure the resulting addresses
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
156 are really in the direct page since the linker does not know what the direct
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
157 page is supposed to be and does not emit errors for byte overflows.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
158 </para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
159
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
160 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
161 It is also possible to use external references in an eight bit immediate
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
162 mode instruction. In this case, only the low order eight bits will be used.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
163 Again, no byte overflows will be flagged.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
164 </para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
165
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
166
109
f21a5593a661 Updated docs
lost
parents:
diff changeset
167 </section>
f21a5593a661 Updated docs
lost
parents:
diff changeset
168
f21a5593a661 Updated docs
lost
parents:
diff changeset
169 </chapter>
f21a5593a661 Updated docs
lost
parents:
diff changeset
170
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
171 <chapter>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
172 <title>LWASM</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
173 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
174 The LWTOOLS assembler is called LWASM. This chapter documents the various
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
175 features of the assembler. It is not, however, a tutorial on 6x09 assembly
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
176 language programming.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
177 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
178
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
179 <section>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
180 <title>Command Line Options</title>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
181 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
182 The binary for LWASM is called "lwasm". Note that the binary is in lower
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
183 case. lwasm takes the following command line arguments.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
184 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
185
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
186 <variablelist>
231
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
187
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
188 <varlistentry>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
189 <term><option>--6309</option></term>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
190 <term><option>-3</option></term>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
191 <listitem>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
192 <para>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
193 This will cause the assembler to accept the additional instructions available
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
194 on the 6309 processor. This is the default mode; this option is provided for
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
195 completeness and to override preset command arguments.
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
196 </para>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
197 </listitem>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
198 </varlistentry>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
199
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
200 <varlistentry>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
201 <term><option>--6809</option></term>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
202 <term><option>-9</option></term>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
203 <listitem>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
204 <para>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
205 This will cause the assembler to reject instructions that are only available
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
206 on the 6309 processor.
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
207 </para>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
208 </listitem>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
209 </varlistentry>
10abe422efce Documented the --6309 and --6809 options
lost
parents: 227
diff changeset
210
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
211 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
212 <term><option>--decb</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
213 <term><option>-b</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
214 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
215 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
216 Select the DECB output format target. Equivalent to <option>--format=decb</option>.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
217 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
218 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
219 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
220
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
221 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
222 <term><option>--format=type</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
223 <term><option>-f type</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
224 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
225 <para>
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
226 Select the output format. Valid values are <option>obj</option> for the
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
227 object file target, <option>decb</option> for the DECB LOADM format,
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
228 <option>os9</option> for creating OS9 modules, and <option>raw</option> for
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
229 a raw binary.
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
230 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
231 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
232 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
233
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
234 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
235 <term><option>--list[=file]</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
236 <term><option>-l[file]</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
237 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
238 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
239 Cause LWASM to generate a listing. If <option>file</option> is specified,
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
240 the listing will go to that file. Otherwise it will go to the standard output
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
241 stream. By default, no listing is generated.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
242 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
243 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
244 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
245
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
246 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
247 <term><option>--obj</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
248 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
249 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
250 Select the proprietary object file format as the output target.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
251 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
252 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
253 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
254
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
255 <varlistentry>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
256 <term><option>--output=FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
257 <term><option>-o FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
258 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
259 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
260 This option specifies the name of the output file. If not specified, the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
261 default is <option>a.out</option>.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
262 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
263 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
264 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
265
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
266 <varlistentry>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
267 <term><option>--pragma=pragma</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
268 <term><option>-p pragma</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
269 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
270 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
271 Specify assembler pragmas. Multiple pragmas are separated by commas. The
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
272 pragmas accepted are the same as for the PRAGMA assembler directive described
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
273 below.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
274 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
275 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
276 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
277
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
278 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
279 <term><option>--raw</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
280 <term><option>-r</option></term>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
281 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
282 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
283 Select raw binary as the output target.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
284 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
285 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
286 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
287
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
288 <varlistentry>
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
289 <term><option>--includedir=path</option></term>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
290 <term><option>-I path</option></term>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
291 <listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
292 <para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
293 Add <option>path</option> to the end of the include path.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
294 </para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
295 </listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
296 </varlistentry>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
297
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
298 <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
299 <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
300 <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
301 <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
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 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
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 </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
306 </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
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 <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
309 <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
310 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
311 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
312 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
313 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
314 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
315 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
316
afe30454382f Made development 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 <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
318 <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
319 <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
320 <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
321 <para>
afe30454382f Made development 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 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
323 </para>
afe30454382f Made development 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 </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
325 </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
326
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
327 <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
328 <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
329 <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
330 <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
331 <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
332 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
333 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
334 </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
335 </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
336 </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
337
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
338 </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
339
afe30454382f Made development 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 </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
341
afe30454382f Made development 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 <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
343 <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
344 <para>
233
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
345 LWASM supports all documented MC6809 instructions as defined by Motorola.
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
346 It also supports all known HD6309 instructions. While there is general
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
347 agreement on the pneumonics for most of the 6309 instructions, there is some
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
348 variance with the block transfer instructions. TFM for all four variations
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
349 seems to have gained the most traction and, thus, this is the form that is
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
350 recommended for LWASM. However, it also supports COPY, COPY-, IMP, EXP,
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
351 TFRP, TFRM, TFRS, and TFRR. It further adds COPY+ as a synomym for COPY,
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
352 IMPLODE for IMP, and EXPAND for EXP.
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
353 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
354
233
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
355 <para>By default, LWASM accepts 6309 instructions. However, using the
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
356 <parameter>--6809</parameter> parameter, you can cause it to throw errors on
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
357 6309 instructions instead.</para>
efda73d44e1b Updated discussion of assembly dialects
lost
parents: 232
diff changeset
358
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
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 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
361 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
362 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
363 </para>
afe30454382f Made development 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
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
365 <para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
366 Additionally, LWASM supports using the asterisk ("*") to indicate
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
367 base page addressing. This should not be used in hand-written source code,
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
368 however, because it is non-standard and may or may not be present in future
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
369 versions of LWASM.
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
370 </para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
371
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
372 </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
373
afe30454382f Made development 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 <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
375 <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
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 <para>
afe30454382f Made development 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 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
379 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
380 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
381 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
382 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
383 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
384 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
385 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
386 <para>
afe30454382f Made development 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 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
388 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
389 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
390 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
391 </para>
afe30454382f Made development 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 <para>
afe30454382f Made development 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 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
394 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
395 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
396 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
397 </para>
afe30454382f Made development 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
afe30454382f Made development 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 <para>
175
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
400 For compatibility with the output generated by some C preprocessors, LWASM
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
401 will also ignore lines that begin with a #. This should not be used as a general
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
402 comment character, however.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
403 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
404
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
405 <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
406 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
407 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
408 </para>
afe30454382f Made development 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
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
410 <para> As of version 2.6, LWASM supports files with line numbers. If line
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
411 numbers are present, the line must start with a digit. The line number
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
412 itself must consist only of digits. The line number must then be followed
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
413 by either the end of the line or exactly one white space character. After
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
414 that white space character, the lines are interpreted exactly as above.
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
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
afe30454382f Made development 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 </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
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 <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
420 <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
421
afe30454382f Made development 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 <para>
afe30454382f Made development 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 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
424 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
425 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
426 </para>
afe30454382f Made development 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
afe30454382f Made development 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 <para>
afe30454382f Made development 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 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
430 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
431 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
432 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
433 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
434 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
435 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
436 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
437 </para>
afe30454382f Made development 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
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
439 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
440 By default, unless assembling to the os9 target, a "$" in the symbol will
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
441 also make it local. This can be controlled by the "dollarlocal" and
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
442 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, For
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
443 the os9 target, a "$" in the symbol will not make it considered local while
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
444 for all other targets it will.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
445 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
446
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
447 </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
448
afe30454382f Made development 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 <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
450 <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
451 <para>
175
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
452
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
453 Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
454 numbers may be prefixed with a "%" symbol or suffixed with a "b" or "B".
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
455 Octal numbers may be prefixed with "@" or suffixed with "Q", "q", "O", or
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
456 "o". Hexadecimal numbers may be prefixed with "$", "0x" or "0X", or suffixed
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
457 with "H". No prefix or suffix is required for decimal numbers but they can
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
458 be prefixed with "&amp;" if desired. Any constant which begins with a letter
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
459 must be expressed with the correct prefix base identifier or be prefixed
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
460 with a 0. Thus hexadecimal FF would have to be written either 0FFH or $FF.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
461 Numbers are not case sensitive.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
462
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
463 </para>
afe30454382f Made development 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
afe30454382f Made development 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 <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
466 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
467 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
468
afe30454382f Made development 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 <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
470 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
471 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
472
afe30454382f Made development 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 <para>
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
474
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
475 LWASM supports the following basic binary operators: +, -, *, /, and %.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
476 These represent addition, subtraction, multiplication, division, and
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
477 modulus. It also supports unary negation and unary 1's complement (- and ^
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
478 respectively). It is also possible to use ~ for the unary 1's complement
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
479 operator. For completeness, a unary positive (+) is supported though it is
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
480 a no-op. LWASM also supports using |, &, and ^ for bitwise or, bitwise and,
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
481 and bitwise exclusive or respectively.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
482
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
483 </para>
afe30454382f Made development 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
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
485 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
486
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
487 Operator precedence follows the usual rules. Multiplication, division, and
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
488 modulus take precedence over addition and subtraction. Unary operators take
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
489 precedence over binary operators. Bitwise operators are lower precdence
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
490 than addition and subtraction. To force a specific order of evaluation,
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
491 parentheses can be used in the usual manner.
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
492
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
493 </para>
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
494
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
495 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
496
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
497 As of LWASM 2.5, the operators && and || are recognized for boolean and and
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
498 boolean or respectively. They will return either 0 or 1 (false or true).
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
499 They have the lowest precedence of all the binary operators.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
500
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
501 </para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
502
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
503 </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
504
afe30454382f Made development 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 <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
506 <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
507 <para>
afe30454382f Made development 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 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
509 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
510 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
511 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
512 </para>
afe30454382f Made development 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
afe30454382f Made development 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 <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
515 <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
516 <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
517 <varlistentry><term>FCB <parameter>expr[,...]</parameter></term>
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
518 <term>.DB <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
519 <term>.BYTE <parameter>expr[,...]</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
520 <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
521 <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
522 </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
523 </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
524
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
525 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
526 <term>FDB <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
527 <term>.DW <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
528 <term>.WORD <parameter>expr[,...]</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
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>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
531 </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
532 </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
533
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
534 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
535 <term>FQB <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
536 <term>.QUAD <parameter>expr[,...]</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
537 <term>.4BYTE <parameter>expr[,...]</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
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 <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
540 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
541 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
542
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
543 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
544 <term>FCC <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
545 <term>.ASCII <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
546 <term>.STR <parameter>string</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
547 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
548 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
549 Include a 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
550 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
551 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
552 </para>
afe30454382f Made development 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 </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
554 </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
555
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
556 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
557 <term>FCN <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
558 <term>.ASCIZ <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
559 <term>.STRZ <parameter>string</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
560 <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
561 <para>
afe30454382f Made development 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 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
563 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
564 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
565 the string.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
566 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
567 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
568 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
569
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
570 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
571 <term>FCS <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
572 <term>.ASCIS <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
573 <term>.STRS <parameter>string</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
574 <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
575 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
576 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
577 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
578 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
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><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
584 <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
585 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
586 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
587 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
588 </para>
afe30454382f Made development 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 </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
590 </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
591
afe30454382f Made development 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 <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
593 <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
594 <para>
afe30454382f Made development 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 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
596 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
597 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
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><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
603 <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
604 <para>
afe30454382f Made development 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 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
606 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
607 permitted.
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
608 </para>
afe30454382f Made development 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 </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
610 </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
611
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
612 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
613 <term>RMB <parameter>expr</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
614 <term>.BLKB <parameter>expr</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
615 <term>.DS <parameter>expr</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
616 <term>.RS <parameter>expr</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
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 <para>
afe30454382f Made development 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 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
620 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
621 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
622 </para>
afe30454382f Made development 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 </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
624 </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
625
afe30454382f Made development 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 <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
627 <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
628 <para>
afe30454382f Made development 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 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
630 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
631 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
632 </para>
afe30454382f Made development 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 </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
634 </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
635
afe30454382f Made development 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 <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
637 <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
638 <para>
afe30454382f Made development 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 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
640 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
641 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
642 </para>
afe30454382f Made development 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 </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
644 </varlistentry>
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
645
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
646 <varlistentry>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
647 <term>INCLUDEBIN <parameter>filename</parameter></term>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
648 <listitem>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
649 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
650 Treat the contents of <parameter>filename</parameter> as a string of bytes to
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
651 be included literally at the current assembly point. This has the same effect
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
652 as converting the file contents to a series of FCB statements and including
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
653 those at the current assembly point.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
654 </para>
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
655
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
656 <para> If <parameter>filename</parameter> beings with a /, the file name
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
657 will be taken as absolute. Otherwise, the current directory will be
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
658 searched followed by the search path in the order specified.</para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
659
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
660 <para> Please note that absolute path detection including drive letters will
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
661 not function correctly on Windows platforms. Non-absolute inclusion will
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
662 work, however.</para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
663
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
664 </listitem>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
665 </varlistentry>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
666
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
667 </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
668
afe30454382f Made development 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 </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
670
afe30454382f Made development 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 <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
672 <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
673 <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
674 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
675
afe30454382f Made development 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 <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
677 <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
678 <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
679 <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
680 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
681 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
682 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
683 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
684 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
685 </para>
afe30454382f Made development 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 </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
687 </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
688
afe30454382f Made development 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 <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
690 <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
691 <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
692 <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
693 <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
694 </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
695 </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
696
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
697 <varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
698 <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
699 <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
700 <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
701 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
702 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
703 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
704 </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
705 </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
706
afe30454382f Made development 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 <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
708 <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
709 <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
710 <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
711 <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
712 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
713 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
714 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
715 </para>
afe30454382f Made development 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 <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
717 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
718 </listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
719 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
720
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
721 <varlistentry>
235
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
722 <term>ALIGN <parameter>expr</parameter>[,<parameter>value</parameter>]</term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
723 <listitem>
235
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
724
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
725 <para>Force the current assembly address to be a multiple of
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
726 <parameter>expr</parameter>. If <parameter>value</parameter> is not
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
727 specified, a series of NUL bytes is output to force the alignment, if
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
728 required. Otherwise, the low order 8 bits of <parameter>value</parameter>
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
729 will be used as the fill. The alignment value must be fully resolved on the
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
730 first pass because it affects the addresses of subsquent instructions.
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
731 However, <parameter>value</parameter> may include forward references; as
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
732 long as it resolves to a constant for the second pass, the value will be
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
733 accepted.</para>
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
734
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
735 <para>Unless <parameter>value</parameter> is specified as something like $12,
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
736 this directive is not suitable for inclusion in the middle of actual code.
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
737 The default padding value is $00 which is intended to be used within data
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
738 blocks. </para>
aa0056ca7319 Added a padding value for the ALIGN directive
lost
parents: 233
diff changeset
739
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
740 </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
741 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
742
afe30454382f Made development 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 </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
744
afe30454382f Made development 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 </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
746
afe30454382f Made development 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 <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
748 <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
749 <para>
afe30454382f Made development 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 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
751 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
752 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
753 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
754 <para>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
755 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
756 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
757 <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
758 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
759 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
760 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
761
afe30454382f Made development 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 <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
763 <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
764 <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
765 <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
766 <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
767 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
768 </para>
afe30454382f Made development 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 </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
770 </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
771
afe30454382f Made development 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 <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
773 <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
774 <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
775 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
776 <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
777 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
778 </para>
afe30454382f Made development 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 </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
780 </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
781
afe30454382f Made development 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 <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
783 <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
784 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
785 <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
786 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
787 </para>
afe30454382f Made development 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 </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
789 </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
790
afe30454382f Made development 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 <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
792 <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
793 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
794 <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
795 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
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 </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
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 <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
801 <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
802 <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
803 <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
804 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
805 </para>
afe30454382f Made development 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 </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
807 </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
808
afe30454382f Made development 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 <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
810 <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
811 <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
812 <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
813 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
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 </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
816 </varlistentry>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
817
afe30454382f Made development 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 <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
819 <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
820 <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
821 <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
822 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
823 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
824 </para>
afe30454382f Made development 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 </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
826 </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
827
afe30454382f Made development 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 <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
829 <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
830 <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
831 <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
832 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
833 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
834 </para>
afe30454382f Made development 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 </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
836 </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
837
afe30454382f Made development 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 <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
839 <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
840 <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
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 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
843 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
844 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
845 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
846 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
847 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
848 </para>
afe30454382f Made development 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 </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
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 <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
852 <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
853 <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
854 <para>
afe30454382f Made development 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 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
856 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
857 </para>
afe30454382f Made development 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 </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
859 </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
860
afe30454382f Made development 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 </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
862 </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
863
afe30454382f Made development 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 <section>
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
865 <title>OS9 Target Directives</title>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
866
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
867 <para>This section includes directives that apply solely to the OS9
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
868 target.</para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
869
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
870 <variablelist>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
871
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
872 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
873 <term>OS9 <parameter>syscall</parameter></term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
874 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
875 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
876
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
877 This directive generates a call to the specified system call. <parameter>syscall</parameter> may be an arbitrary expression.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
878
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
879 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
880 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
881 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
882
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
883 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
884 <term>MOD <parameter>size</parameter>,<parameter>name</parameter>,<parameter>type</parameter>,<parameter>flags</parameter>,<parameter>execoff</parameter>,<parameter>datasize</parameter></term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
885 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
886 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
887
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
888 This tells LWASM that the beginning of the actual module is here. It will
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
889 generate a module header based on the parameters specified. It will also
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
890 begin calcuating the module CRC.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
891
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
892 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
893
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
894 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
895
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
896 The precise meaning of the various parameters is beyond the scope of this
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
897 document since it is not a tutorial on OS9 module programming.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
898
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
899 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
900
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
901 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
902 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
903
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
904 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
905 <term>EMOD</term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
906 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
907 <para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
908
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
909 This marks the end of a module and causes LWASM to emit the calculated CRC
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
910 for the module.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
911
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
912 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
913 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
914
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
915 </variablelist>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
916 </section>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
917
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
918 <section>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
919 <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
920
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
921 <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
922 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
923
afe30454382f Made development 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 <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
925
afe30454382f Made development 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 <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
927 <term>INCLUDE <parameter>filename</parameter></term>
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
928 <term>USE <parameter>filename</parameter></term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
929
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
930 <listitem> <para> Include the contents of <parameter>filename</parameter> at
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
931 this point in the assembly as though it were a part of the file currently
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
932 being processed. Note that if whitespace appears in the name of the file,
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
933 you must enclose <parameter>filename</parameter> in quotes.
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
934 </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
935
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
936 <para>
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
937 Note that the USE variation is provided only for compatibility with other
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
938 assemblers. It is recommended to use the INCLUDE variation.</para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
939
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
940 </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
941 </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
942
afe30454382f Made development 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 <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
944 <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
945 <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
946 <para>
afe30454382f Made development 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 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
948 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
949 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
950 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
951 </para>
afe30454382f Made development 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 </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
953 </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
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 <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
956 <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
957 <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
958 <para>
afe30454382f Made development 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 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
960 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
961 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
962 </para>
afe30454382f Made development 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 </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
964 </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
965
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
966 <varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
967 <term>.MODULE <parameter>string</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
968 <listitem>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
969 <para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
970 This directive is ignored for most output targets. If the output target
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
971 supports encoding a module name into it, <parameter>string</parameter>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
972 will be used as the module name.
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
973 </para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
974 <para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
975 As of version 2.2, no supported output targets support this directive.
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
976 </para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
977 </listitem>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
978 </varlistentry>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
979
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
980 </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
981 </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
982
afe30454382f Made development 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 </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
984
afe30454382f Made development 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 <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
986 <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
987 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
988 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
989 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
990 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
991 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
992 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
993 <para>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
994 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
995 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
996 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
997 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
998 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
999 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
1000 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
1001 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
1002 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
1003 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1004 <para>
afe30454382f Made development 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 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
1006 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
1007 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
1008 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1009 <para>
afe30454382f Made development 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 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
1011 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
1012 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
1013 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
1014
afe30454382f Made development 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 <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
1016 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
1017 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
1018 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
1019 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
1020 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
1021 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
1022 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
1023 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
1024 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1025 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1026 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
1027 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
1028 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
1029 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
1030 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1031
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1032 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1033 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
1034 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
1035 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
1036 </para>
afe30454382f Made development 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
afe30454382f Made development 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 <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
1039
afe30454382f Made development 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 <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
1041 <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
1042 <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
1043 <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
1044 <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
1045 <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
1046 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
1047 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
1048 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
1049 </para>
afe30454382f Made development 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 </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
1051 </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
1052
afe30454382f Made development 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 <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
1054 <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
1055 <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
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 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
1058 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
1059 </para>
afe30454382f Made development 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 </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
1061 </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
1062
afe30454382f Made development 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 </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
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>
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1066 <title>Structures</title>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1067 <para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1068
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1069 Structures are used to group related data in a fixed structure. A structure
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1070 consists a number of fields, defined in sequential order and which take up
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1071 specified size. The assembler does not enforce any means of access within a
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1072 structure; it assumes that whatever you are doing, you intended to do.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1073 There are two pseudo ops that are used for defining structures.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1074
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1075 </para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1076
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1077 <variablelist>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1078 <varlistentry>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1079 <term><parameter>structname</parameter> STRUCT</term>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1080 <listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1081 <para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1082
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1083 This directive is used to begin the definition of a structure with name
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1084 <parameter>structname</parameter>. Subsequent statements all form part of
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1085 the structure definition until the end of the structure is declared.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1086
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1087 </para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1088 </listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1089 </varlistentry>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1090 <varlistentry>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1091 <term>ENDSTRUCT</term>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1092 <listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1093 <para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1094 This directive ends the definition of the structure.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1095 </para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1096 </listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1097 </varlistentry>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1098 </variablelist>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1099
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1100 <para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1101
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1102 Within a structure definition, only reservation pseudo ops are permitted.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1103 Anything else will cause an assembly error.
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1104 </para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1105
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1106 <para> Once a structure is defined, you can reserve an area of memory in the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1107 same structure by using the structure name as the opcode. Structures can
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1108 also contain fields that are themselves structures. See the example
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1109 below.</para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1110
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1111 <programlisting>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1112 tstruct2 STRUCT
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1113 f1 rmb 1
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1114 f2 rmb 1
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1115 ENDSTRUCT
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1116
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1117 tstruct STRUCT
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1118 field1 rmb 2
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1119 field2 rmb 3
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1120 field3 tstruct2
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1121 ENDSTRUCT
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1122
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1123 ORG $2000
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1124 var1 tstruct
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1125 var2 tstruct2
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1126 </programlisting>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1127
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1128 <para>Fields are referenced using a dot (.) as a separator. To refer to the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1129 generic offset within a structure, use the structure name to the left of the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1130 dot. If referring to a field within an actual variable, use the variable's
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1131 symbol name to the left of the dot.</para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1132
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1133 <para>You can also refer to the actual size of a structure (or a variable
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1134 declared as a structure) using the special symbol sizeof{structname} where
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1135 structname will be the name of the structure or the name of the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1136 variable.</para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1137
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1138 <para>Essentially, structures are a shortcut for defining a vast number of
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1139 symbols. When a structure is defined, the assembler creates symbols for the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1140 various fields in the form structname.fieldname as well as the appropriate
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1141 sizeof{structname} symbol. When a variable is declared as a structure, the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1142 assembler does the same thing using the name of the variable. You will see
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1143 these symbols in the symbol table when the assembler is instructed to
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1144 provide a listing. For instance, the above listing will create the
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1145 following symbols (symbol values in parentheses): tstruct2.f1 (0),
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1146 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1147 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6),
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1148 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1149 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1150 var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1151 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1152
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1153 </section>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1154
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1155 <section>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1156 <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
1157 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1158 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
1159 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
1160 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
1161 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
1162 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
1163 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
1164 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
1165 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
1166 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
1167 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1168
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1169 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1170 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
1171 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
1172 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
1173 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
1174 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
1175 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
1176 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
1177 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
1178 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
1179 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
1180 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
1181 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
1182 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
1183 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
1184 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1185
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1186 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1187 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
1188 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
1189 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
1190 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
1191 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
1192 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
1193 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
1194 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1195
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1196 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1197 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
1198 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
1199 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
1200 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
1201 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
1202 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1203
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1204 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1205 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
1206 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
1207 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
1208 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
1209 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
1210 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
1211 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1212
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1213 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1214 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
1215 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
1216 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
1217 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
1218 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
1219 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
1220 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1221
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1222 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1223 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
1224 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
1225 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
1226 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
1227 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
1228 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
1229 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
1230 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
1231 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
1232 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
1233 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1234
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1235 <para>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
1236
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1237 <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
1238 <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
1239 <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
1240 <term>SECT <parameter>name[,flags]</parameter></term>
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1241 <term>.AREA <parameter>name[,flags]</parameter></term>
145
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1242 <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
1243 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1244 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
1245 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
1246 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
1247 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
1248 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
1249 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
1250 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1251 <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
1252 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
1253 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
1254 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
1255 <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
1256 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
1257 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
1258 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
1259 </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
1260 <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
1261 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
1262 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
1263 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
1264 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1265 </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
1266 </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
1267
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1268 <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
1269 <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
1270 <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
1271 <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
1272 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1273 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1274 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
1275 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
1276 </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
1277 </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
1278
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1279 <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
1280 <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
1281 <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
1282 <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
1283 <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
1284 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1285 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
1286 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
1287 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
1288 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
1289 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
1290 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
1291 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
1292 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1293 </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
1294 </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
1295
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1296 <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
1297 <term><parameter>sym</parameter> EXPORT</term>
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1298 <term><parameter>sym</parameter> .GLOBL</term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1299
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1300 <term>EXPORT <parameter>sym</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1301 <term>.GLOBL <parameter>sym</parameter></term>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1302
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
1303 <listitem>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1304 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1305 This 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
1306 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
1307 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
1308 </para>
167
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1309 <para>
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1310 Note that <parameter>sym</parameter> may appear as the operand or as the
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1311 statement's symbol. If there is a symbol on the statement, that will
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1312 take precedence over any operand that is present.
751b99efb1fc Updated docs
lost
parents: 159
diff changeset
1313 </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
1314 </listitem>
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1315
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
1316 </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
1317
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1318 <varlistentry>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1319 <term><parameter>sym</parameter>EXTDEP</term>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1320 <listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1321
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1322 <para>This directive forces an external dependency on
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1323 <parameter>sym</parameter>, even if it is never referenced anywhere else in
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1324 this file.</para>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1325
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1326 </listitem>
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
1327 </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
1328 </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
1329
afe30454382f Made development 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 </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
1331
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1332 <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
1333 <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
1334 <para>
afe30454382f Made development 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 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
1336 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
1337 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
1338 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
1339 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
1340 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
1341 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1342
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1343 <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
1344 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
1345 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
1346 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
1347 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1348
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1349 <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
1350 <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
1351 <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
1352 <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
1353 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1354 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
1355 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
1356 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
1357 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
1358 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1359 </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
1360 </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
1361
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1362 <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
1363 <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
1364 <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
1365 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1366 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
1367 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
1368 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
1369 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
1370 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
1371 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1372 </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
1373 </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
1374 </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
1375
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1376 <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
1377 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
1378 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
1379 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
1380 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
1381
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1382 <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
1383
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1384 <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
1385 <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
1386 <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
1387 <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
1388 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1389 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
1390 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
1391 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
1392 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
1393 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
1394 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1395 </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
1396 </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
1397
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1398 <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
1399 <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
1400 <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
1401 <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
1402 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
1403 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
1404 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
1405 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
1406 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
1407 </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
1408 </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
1409 </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
1410
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
1411 <varlistentry>
227
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1412 <term>importundefexport</term>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1413 <listitem>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1414 <para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1415 This pragma is only valid for targets that support external references. When
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1416 in force, it will cause the EXPORT directive to act as IMPORT if the symbol
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1417 to be exported is not defined. This is provided for compatibility with the
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1418 output of gcc6809 and should not be used in hand written code. Because of
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1419 the confusion this pragma can cause, it is disabled by default.
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1420 </para>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1421 </listitem>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1422 </varlistentry>
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1423
4c60c3a09597 Various updates to the manual
lost
parents: 186
diff changeset
1424 <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
1425 <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
1426 <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
1427 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1428 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
1429 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
1430 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
1431 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
1432 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
1433 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
1434 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1435 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1436 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
1437 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
1438 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
1439 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
1440 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
1441 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
1442 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
1443 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1444 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1445 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
1446 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
1447 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
1448 </para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1449 </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
1450 </varlistentry>
237
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1451
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1452 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1453 <term>dollarlocal</term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1454 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1455
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1456 <para>When set, a "$" in a symbol makes it local. When not set, "$" does not
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1457 cause a symbol to be local. It is set by default except when using the OS9
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1458 target.</para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1459
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1460 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1461 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1462
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1463 <varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1464 <term>dollarnotlocal</term>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1465 <listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1466
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1467 <para> This is the same as the "dollarlocal" pragma except its sense is
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1468 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1469 "nodollarlocal" and "dollarnotlocal" are equivalent. </para>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1470
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1471 </listitem>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1472 </varlistentry>
dca5938a64aa Updated documentation to reflect recent udates to LWASM
lost
parents: 235
diff changeset
1473
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
1474 </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
1475
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1476 </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
1477
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1478 </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
1479
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1480 <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
1481 <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
1482 <para>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1483 The LWTOOLS linker is called LWLINK. This chapter documents the various features
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1484 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
1485 </para>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1486
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1487 <section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1488 <title>Command Line Options</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1489 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1490 The binary for LWLINK is called "lwlink". Note that the binary is in lower
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1491 case. lwlink takes the following command line arguments.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1492 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1493 <variablelist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1494 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1495 <term><option>--decb</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1496 <term><option>-b</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1497 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1498 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1499 Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1500 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1501 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1502 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1503
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1504 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1505 <term><option>--output=FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1506 <term><option>-o FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1507 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1508 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1509 This option specifies the name of the output file. If not specified, the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1510 default is <option>a.out</option>.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1511 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1512 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1513 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1514
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1515 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1516 <term><option>--format=TYPE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1517 <term><option>-f TYPE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1518 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1519 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1520 This option specifies the output format. Valid values are <option>decb</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1521 and <option>raw</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1522 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1523 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1524 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1525
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1526 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1527 <term><option>--raw</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1528 <term><option>-r</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1529 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1530 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1531 This option specifies the raw output format.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1532 It is equivalent to <option>--format=raw</option>.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1533 and <option>raw</option>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1534 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1535 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1536 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1537
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1538 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1539 <term><option>--script=FILE</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1540 <term><option>-s</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1541 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1542 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1543 This option allows specifying a linking script to override the linker's
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1544 built in defaults.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1545 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1546 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1547 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1548
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1549 <varlistentry>
186
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1550 <term><option>--section-base=SECT=BASE</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1551 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1552 <para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1553 Cause section SECT to load at base address BASE. This will be prepended
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1554 to the built-in link script. It is ignored if a link script is provided.
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1555 </para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1556 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1557 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1558
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1559 <varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1560 <term><option>--map=FILE</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1561 <term><option>-m FILE</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1562 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1563 <para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1564 This will output a description of the link result to FILE.
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1565 </para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1566 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1567 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1568
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1569 <varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1570 <term><option>--library=LIBSPEC</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1571 <term><option>-l LIBSPEC</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1572 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1573 <para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1574 Load a library using the library search path. LIBSPEC will have "lib" prepended
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1575 and ".a" appended.
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1576 </para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1577 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1578 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1579
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1580 <varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1581 <term><option>--library-path=DIR</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1582 <term><option>-L DIR</option></term>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1583 <listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1584 <para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1585 Add DIR to the library search path.
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1586 </para>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1587 </listitem>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1588 </varlistentry>
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1589
bc2fae9438eb Updated documentation to reflect recent changes
lost
parents: 175
diff changeset
1590 <varlistentry>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1591 <term><option>--debug</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1592 <term><option>-d</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1593 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1594 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1595 This option increases the debugging level. It is only useful for LWTOOLS
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1596 developers.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1597 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1598 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1599 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1600
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1601 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1602 <term><option>--help</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1603 <term><option>-?</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1604 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1605 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1606 This provides a listing of command line options and a brief description
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1607 of each.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1608 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1609 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1610 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1611
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1612 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1613 <term><option>--usage</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1614 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1615 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1616 This will display a usage summary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1617 of each.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1618 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1619 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1620 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1621
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1622
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1623 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1624 <term><option>--version</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1625 <term><option>-V</option></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1626 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1627 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1628 This will display the version of LWLINK.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1629 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1630 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1631 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1632
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1633 </section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1634
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1635 <section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1636 <title>Linker Operation</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1637
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1638 <para>
175
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1639
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1640 LWLINK takes one or more files in supported input formats and links them
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1641 into a single binary. Currently supported formats are the LWTOOLS object
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1642 file format and the archive format used by LWAR. While the precise method is
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1643 slightly different, linking can be conceptualized as the following steps.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1644
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1645 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1646
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1647 <orderedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1648 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1649 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1650 First, the linker loads a linking script. If no script is specified, it
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1651 loads a built-in default script based on the output format selected. This
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1652 script tells the linker how to lay out the various sections in the final
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1653 binary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1654 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1655 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1656
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1657 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1658 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1659 Next, the linker reads all the input files into memory. At this time, it
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1660 flags any format errors in those files. It constructs a table of symbols
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1661 for each object at this time.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1662 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1663 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1664
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1665 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1666 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1667 The linker then proceeds with organizing the sections loaded from each file
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1668 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
1669 to each symbol defined in each object file. At this time, the linker may
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1670 also collapse different instances of the same section name into a single
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1671 section by appending the data from each subsequent instance of the section
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1672 to the first instance of the section.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1673 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1674 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1675
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1676 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1677 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1678 Next, the linker looks through every object file for every incomplete reference.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1679 It then attempts to fully resolve that reference. If it cannot do so, it
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1680 throws an error. Once a reference is resolved, the value is placed into
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1681 the binary code at the specified section. It should be noted that an
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1682 incomplete reference can reference either a symbol internal to the object
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1683 file or an external symbol which is in the export list of another object
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1684 file.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1685 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1686 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1687
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1688 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1689 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1690 If all of the above steps are successful, the linker opens the output file
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1691 and actually constructs the binary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1692 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1693 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1694 </orderedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1695
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1696 </section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1697
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1698 <section
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1699 <title>Linking Scripts</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1700 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1701 A linker script is used to instruct the linker about how to assemble the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1702 various sections into a completed binary. It consists of a series of
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1703 directives which are considered in the order they are encountered.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1704 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1705 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1706 The sections will appear in the resulting binary in the order they are
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1707 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
1708 section did exist but had a zero size, no relocations, and no exports.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1709 A section should only be referenced once. Any subsequent references will have
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1710 an undefined effect.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1711 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1712
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1713 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1714 All numbers are in linking scripts are specified in hexadecimal. All directives
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1715 are case sensitive although the hexadecimal numbers are not.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1716 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1717
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1718 <para>A section name can be specified as a "*", then any section not
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1719 already matched by the script will be matched. The "*" can be followed
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1720 by a comma and a flag to narrow the section down slightly, also.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1721 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
1722 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
1723 bss will be matched.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1724 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1725
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1726 <para>The following directives are understood in a linker script.</para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1727 <variablelist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1728 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1729 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1730 <listitem><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1731
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1732 This causes the section <parameter>name</parameter> to load at
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1733 <parameter>addr</parameter>. For the raw target, only one "load at" entry is
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1734 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
1735 it affects the addresses the linker assigns to symbols but has no other
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1736 affect on the output. bss sections may all have separate load addresses but
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1737 since they will not appear in the binary anyway, this is okay.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1738 </para><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1739 For the decb target, each "load" entry will cause a new "block" to be
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1740 output to the binary which will contain the load address. It is legal for
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1741 sections to overlap in this manner - the linker assumes the loader will sort
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1742 everything out.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1743 </para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1744 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1745
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1746 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1747 <term>section <parameter>name</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1748 <listitem><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1749
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1750 This will cause the section <parameter>name</parameter> to load after the previously listed
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1751 section.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1752 </para></listitem></varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1753 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1754 <term>exec <parameter>addr or sym</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1755 <listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1756 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1757 This will cause the execution address (entry point) to be the address
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1758 specified (in hex) or the specified symbol name. The symbol name must
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1759 match a symbol that is exported by one of the object files being linked.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1760 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
1761 resulting file. If not specified, the entry point is assumed to be address 0
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1762 which is probably not what you want. The default link scripts for targets
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1763 that support this directive automatically starts at the beginning of the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1764 first section (usually "init" or "code") that is emitted in the binary.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1765 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1766 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1767 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1768
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1769 <varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1770 <term>pad <parameter>size</parameter></term>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1771 <listitem><para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1772 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
1773 <parameter>size</parameter> bytes in length. This only makes sense for a raw target.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1774 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1775 </listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1776 </varlistentry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1777 </variablelist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1778
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1779
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1780
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1781 </section>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1782
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
1783 </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
1784
175
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1785 <chapter>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1786 <title>Libraries and LWAR</title>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1787
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1788 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1789 LWTOOLS also includes a tool for managing libraries. These are analogous to
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1790 the static libraries created with the "ar" tool on POSIX systems. Each library
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1791 file contains one or more object files. The linker will treat the object
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1792 files within a library as though they had been specified individually on
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1793 the command line except when resolving external references. External references
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1794 are looked up first within the object files within the library and then, if
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1795 not found, the usual lookup based on the order the files are specified on
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1796 the command line occurs.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1797 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1798
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1799 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1800 The tool for creating these libary files is called LWAR.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1801 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1802
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1803 <section>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1804 <title>Command Line Options</title>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1805 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1806 The binary for LWAR is called "lwar". Note that the binary is in lower
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1807 case. The options lwar understands are listed below. For archive manipulation
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1808 options, the first non-option argument is the name of the archive. All other
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1809 non-option arguments are the names of files to operate on.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1810 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1811
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1812 <variablelist>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1813 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1814 <term><option>--add</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1815 <term><option>-a</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1816 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1817 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1818 This option specifies that an archive is going to have files added to it.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1819 If the archive does not already exist, it is created. New files are added
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1820 to the end of the archive.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1821 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1822 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1823 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1824
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1825 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1826 <term><option>--create</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1827 <term><option>-c</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1828 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1829 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1830 This option specifies that an archive is going to be created and have files
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1831 added to it. If the archive already exists, it is truncated.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1832 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1833 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1834 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1835
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1836 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1837 <term><option>--merge</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1838 <term><option>-m</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1839 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1840 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1841 If specified, any files specified to be added to an archive will be checked
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1842 to see if they are archives themselves. If so, their constituent members are
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1843 added to the archive. This is useful for avoiding archives containing archives.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1844 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1845 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1846 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1847
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1848 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1849 <term><option>--list</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1850 <term><option>-l</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1851 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1852 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1853 This will display a list of the files contained in the archive.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1854 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1855 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1856 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1857
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1858 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1859 <term><option>--debug</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1860 <term><option>-d</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1861 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1862 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1863 This option increases the debugging level. It is only useful for LWTOOLS
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1864 developers.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1865 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1866 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1867 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1868
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1869 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1870 <term><option>--help</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1871 <term><option>-?</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1872 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1873 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1874 This provides a listing of command line options and a brief description
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1875 of each.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1876 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1877 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1878 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1879
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1880 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1881 <term><option>--usage</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1882 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1883 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1884 This will display a usage summary.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1885 of each.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1886 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1887 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1888 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1889
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1890
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1891 <varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1892 <term><option>--version</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1893 <term><option>-V</option></term>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1894 <listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1895 <para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1896 This will display the version of LWLINK.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1897 of each.
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1898 </para>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1899 </listitem>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1900 </varlistentry>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1901
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1902 </section>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1903
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1904 </chapter>
f8ec28ace0c6 Updated docs to reflect recent changes
lost
parents: 167
diff changeset
1905
109
f21a5593a661 Updated docs
lost
parents:
diff changeset
1906 <chapter id="objchap">
f21a5593a661 Updated docs
lost
parents:
diff changeset
1907 <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
1908 <para>
afe30454382f Made development version of LWASM be 2.1, not 3.0, because the next release will be an incremental feature release
lost
parents: 109
diff changeset
1909 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
1910 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
1911 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
1912 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
1913 </para>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1914
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1915 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1916 An object file consists of a series of sections each of which contains a
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1917 list of exported symbols, a list of incomplete references, and a list of
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1918 "local" symbols which may be used in calculating incomplete references. Each
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1919 section will obviously also contain the object code.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1920 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1921
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1922 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1923 Exported symbols must be completely resolved to an address within the
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1924 section it is exported from. That is, an exported symbol must be a constant
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1925 rather than defined in terms of other symbols.</para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1926
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1927 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1928 Each object file starts with a magic number and version number. The magic
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1929 number is the string "LWOBJ16" for this 16 bit object file format. The only
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1930 defined version number is currently 0. Thus, the first 8 bytes of the object
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1931 file are <code>4C574F424A313600</code>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1932 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1933
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1934 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1935 Each section has the following items in order:
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1936 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1937
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1938 <itemizedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1939 <listitem><para>section name</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1940 <listitem><para>flags</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1941 <listitem><para>list of local symbols (and addresses within the section)</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1942 <listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1943 <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
1944 <listitem><para>the actual object code (for non-BSS sections)</para></listitem>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1945 </itemizedlist>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1946
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1947 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1948 The section starts with the name of the section with a NUL termination
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1949 followed by a series of flag bytes terminated by NUL. There are only two
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1950 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
1951 indicates the section is a BSS section. For a BSS section, no actual
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1952 code is included in the object file.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1953 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1954
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1955 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1956 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
1957 sections.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1958 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1959
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1960 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1961 Each entry in the exported and local symbols table consists of the symbol
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1962 (NUL terminated) followed by two bytes which contain the value in big endian
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1963 order. The end of a symbol table is indicated by a NULL symbol name.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1964 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1965
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1966 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1967 Each entry in the incomplete references table consists of an expression
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1968 followed by a 16 bit offset where the reference goes. Expressions are
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1969 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
1970 consists of a single byte which identifies the type of term (see below)
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1971 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
1972 by a NULL expression (only an end of expression term).
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1973 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1974
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1975 <table frame="all"><title>Object File Term Types</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1976 <tgroup cols="2">
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1977 <thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1978 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1979 <entry>TERMTYPE</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1980 <entry>Meaning</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1981 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1982 </thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1983 <tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1984 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1985 <entry>00</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1986 <entry>end of expression</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1987 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1988
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1989 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1990 <entry>01</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1991 <entry>integer (16 bit in big endian order follows)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1992 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1993 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1994 <entry>02</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1995 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1996 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1997
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1998 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
1999 <entry>03</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2000 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2001 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2002
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2003 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2004 <entry>04</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2005 <entry>operator (1 byte operator number)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2006 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2007 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2008 <entry>05</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2009 <entry>section base address reference</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2010 </row>
232
1009f302ac11 Documented the "Flags" term for object files
lost
parents: 231
diff changeset
2011
1009f302ac11 Documented the "Flags" term for object files
lost
parents: 231
diff changeset
2012 <row>
1009f302ac11 Documented the "Flags" term for object files
lost
parents: 231
diff changeset
2013 <entry>FF</entry>
256
6e2d03188d24 Updated manual to reflect updates for 2.6 release
lost
parents: 240
diff changeset
2014 <entry>This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</entry>
232
1009f302ac11 Documented the "Flags" term for object files
lost
parents: 231
diff changeset
2015 </row>
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2016 </tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2017 </tgroup>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2018 </table>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2019
232
1009f302ac11 Documented the "Flags" term for object files
lost
parents: 231
diff changeset
2020
150
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2021 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2022 External references are resolved using other object files while local
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2023 references are resolved using the local symbol table(s) from this file. This
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2024 allows local symbols that are not exported to have the same names as
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2025 exported symbols or external references.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2026 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2027
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2028 <table frame="all"><title>Object File Operator Numbers</title>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2029 <tgroup cols="2">
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2030 <thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2031 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2032 <entry>Number</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2033 <entry>Operator</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2034 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2035 </thead>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2036 <tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2037 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2038 <entry>01</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2039 <entry>addition (+)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2040 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2041 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2042 <entry>02</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2043 <entry>subtraction (-)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2044 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2045 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2046 <entry>03</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2047 <entry>multiplication (*)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2048 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2049 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2050 <entry>04</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2051 <entry>division (/)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2052 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2053 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2054 <entry>05</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2055 <entry>modulus (%)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2056 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2057 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2058 <entry>06</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2059 <entry>integer division (\) (same as division)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2060 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2061
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2062 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2063 <entry>07</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2064 <entry>bitwise and</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2065 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2066
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2067 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2068 <entry>08</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2069 <entry>bitwise or</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2070 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2071
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2072 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2073 <entry>09</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2074 <entry>bitwise xor</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2075 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2076
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2077 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2078 <entry>0A</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2079 <entry>boolean and</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2080 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2081
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2082 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2083 <entry>0B</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2084 <entry>boolean or</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2085 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2086
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2087 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2088 <entry>0C</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2089 <entry>unary negation, 2's complement (-)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2090 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2091
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2092 <row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2093 <entry>0D</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2094 <entry>unary 1's complement (^)</entry>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2095 </row>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2096 </tbody>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2097 </tgroup>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2098 </table>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2099
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2100 <para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2101 An expression is represented in a postfix manner with both operands for
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2102 binary operators preceding the operator and the single operand for unary
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2103 operators preceding the operator.
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2104 </para>
f0881c115010 More major documentation upgrades
lost
parents: 147
diff changeset
2105
109
f21a5593a661 Updated docs
lost
parents:
diff changeset
2106 </chapter>
f21a5593a661 Updated docs
lost
parents:
diff changeset
2107 </book>
f21a5593a661 Updated docs
lost
parents:
diff changeset
2108