annotate doc/manual.docbook.sgml @ 448:5cccf90bf838 3.0 tip

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