annotate doc/manual.docbook.sgml @ 423:079d43b6967b 3.0-beta2 3.0-beta2

Added missing file
author lost@l-w.ca
date Sun, 19 Sep 2010 01:44:47 -0600
parents b2e007c28b8f
children 637f46c5b2b7
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>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
408 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
409 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
410 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
411 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
412 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
413 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
414
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 For compatibility with the output generated by some C preprocessors, LWASM
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
417 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
418 comment character, however.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
419 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
420
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
421 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
422 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
423 the operand fields. Symbols, however, are case sensitive.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
424 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
425
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
426 <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
427 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
428 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
429 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
430 that white space character, the lines are interpreted exactly as above.
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 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
434
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
435 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
436 <title>Symbols</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
437
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 Symbols have no length restriction. They may contain letters, numbers, dots,
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
440 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
441 underscore.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
442 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
443
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
444 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
445 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
446 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
447 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
448 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
449 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
450 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
451 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
452 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
453 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
454
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
455 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
456 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
457 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
458 "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
459 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
460 for all other targets it will.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
461 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
462
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
463 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
464
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
465 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
466 <title>Numbers and Expressions</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
467 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
468
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
469 Numbers can be expressed in binary, octal, decimal, or hexadecimal. Binary
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
470 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
471 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
472 "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
473 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
474 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
475 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
476 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
477 Numbers are not case sensitive.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
478
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
479 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
480
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
481 <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
482 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
483 current source line within expressions. </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
484
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
485 <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
486 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
487 prefixing the characters with a quote (").</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
488
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
489 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
490
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
491 LWASM supports the following basic binary operators: +, -, *, /, and %.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
492 These represent addition, subtraction, multiplication, division, and
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
493 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
494 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
495 operator. For completeness, a unary positive (+) is supported though it is
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
496 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
497 and bitwise exclusive or respectively.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
498
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
499 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
500
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
501 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
502
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
503 Operator precedence follows the usual rules. Multiplication, division, and
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
504 modulus take precedence over addition and subtraction. Unary operators take
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
505 precedence over binary operators. Bitwise operators are lower precdence
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
506 than addition and subtraction. To force a specific order of evaluation,
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
507 parentheses can be used in the usual manner.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
508
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
509 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
510
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
511 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
512
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
513 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
514 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
515 They have the lowest precedence of all the binary operators.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
516
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
517 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
518
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
519 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
520
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
521 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
522 <title>Assembler Directives</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
523 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
524 Various directives can be used to control the behaviour of the
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
525 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
526 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
527 described below.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
528 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
529
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
530 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
531 <title>Data Directives</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
532 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
533 <varlistentry><term>FCB <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
534 <term>.DB <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
535 <term>.BYTE <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
536 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
537 <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
538 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
539 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
540
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
541 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
542 <term>FDB <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
543 <term>.DW <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
544 <term>.WORD <parameter>expr[,...]</parameter></term>
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 <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
547 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
550 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
551 <term>FQB <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
552 <term>.QUAD <parameter>expr[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
553 <term>.4BYTE <parameter>expr[,...]</parameter></term>
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 <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
556 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
559 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
560 <term>FCC <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
561 <term>.ASCII <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
562 <term>.STR <parameter>string</parameter></term>
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
565 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
566 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
567 within the string. The string is included with no modifications>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
568 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
569 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
570 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
571
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
572 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
573 <term>FCN <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
574 <term>.ASCIZ <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
575 <term>.STRZ <parameter>string</parameter></term>
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
578 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
579 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
580 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
581 the string.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
582 </para>
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 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
585
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
586 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
587 <term>FCS <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
588 <term>.ASCIS <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
589 <term>.STRS <parameter>string</parameter></term>
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
592 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
593 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
594 character and cannot appear within the string.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
595 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
596 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
597 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
598
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
599 <varlistentry><term>ZMB <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
600 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
601 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
602 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
603 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
604 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
605 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
606 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
607
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
608 <varlistentry><term>ZMD <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
609 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
610 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
611 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
612 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
613 permitted.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
614 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
615 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
616 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
617
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
618 <varlistentry><term>ZMQ <parameter>expr<parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
619 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
620 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
621 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
622 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
623 permitted.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
624 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
625 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
626 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
627
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
628 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
629 <term>RMB <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
630 <term>.BLKB <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
631 <term>.DS <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
632 <term>.RS <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
633 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
634 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
635 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
636 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
637 The value of the bytes is undefined.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
638 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
639 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
640 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
641
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
642 <varlistentry><term>RMD <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
643 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
644 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
645 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
646 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
647 permitted. The value of the words is undefined.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
648 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
649 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
650 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
651
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
652 <varlistentry><term>RMQ <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
653 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
654 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
655 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
656 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
657 permitted. The value of the double-words is undefined.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
658 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
659 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
660 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
661
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
662 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
663 <term>INCLUDEBIN <parameter>filename</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
664 <listitem>
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 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
667 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
668 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
669 those at the current assembly point.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
670 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
671
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
672 <para> If <parameter>filename</parameter> beings with a /, the file name
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
673 will be taken as absolute. Otherwise, the current directory will be
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
674 searched followed by the search path in the order specified.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
675
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
676 <para> Please note that absolute path detection including drive letters will
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
677 not function correctly on Windows platforms. Non-absolute inclusion will
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
678 work, however.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
679
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
680 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
681 </varlistentry>
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 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
684
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
685 </section>
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 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
688 <title>Address Definition</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
689 <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
690 or the assembly process itself.</para>
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 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
693 <varlistentry><term>ORG <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
694 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
695 <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
696 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
697 permitted within sections when outputting to object files. For the DECB
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
698 target, each ORG directive after which output is generated will cause
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
699 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
700 of symbols when the raw target is used.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
701 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
702 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
703 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
704
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
705 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
706 <term><parameter>sym</parameter> EQU <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
707 <term><parameter>sym</parameter> = <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
708 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
709 <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
710 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
711 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
712
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
713 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
714 <term><parameter>sym</parameter> SET <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 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
718 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
719 that sets its value is undefined.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
720 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
721 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
722
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
723 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
724 <term>SETDP <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
725 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
726 <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
727 <parameter>expr</parameter>. This directive is only advice to the assembler
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
728 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
729 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
730 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
731 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
732 <para>This directive has no effect in the object file target.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
733 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
734 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
735 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
736
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
737 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
738 <term>ALIGN <parameter>expr</parameter>[,<parameter>value</parameter>]</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
739 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
740
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
741 <para>Force the current assembly address to be a multiple of
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
742 <parameter>expr</parameter>. If <parameter>value</parameter> is not
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
743 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
744 required. Otherwise, the low order 8 bits of <parameter>value</parameter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
745 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
746 first pass because it affects the addresses of subsquent instructions.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
747 However, <parameter>value</parameter> may include forward references; as
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
748 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
749 accepted.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
750
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
751 <para>Unless <parameter>value</parameter> is specified as something like $12,
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
752 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
753 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
754 blocks. </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
755
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
756 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
757 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
758
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
759 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
760
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
761 </section>
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 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
764 <title>Conditional Assembly</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
765 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
766 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
767 known at assembly time. Conditionals can be nested arbitrarily deeply. The
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
768 directives associated with conditional assembly are described in this section.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
769 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
770 <para>All conditionals must be fully bracketed. That is, every conditional
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
771 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
772 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
773 <para>Conditional expressions are only evaluated on the first assembly pass.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
774 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
775 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
776 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
777 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
778 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
779 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
780
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
781 <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
782 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
783 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
784 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
785
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
786 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
787 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
788 <term>IFEQ <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
789 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
790 <para>If <parameter>expr</parameter> evaluates to zero, the conditional
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
791 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
792 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
793 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
796 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
797 <term>IFNE <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
798 <term>IF <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
799 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
800 <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
801 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
802 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
803 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
804 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
805
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
806 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
807 <term>IFGT <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
808 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
809 <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
810 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
811 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
812 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
815 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
816 <term>IFGE <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
817 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
818 <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
819 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
820 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
821 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
824 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
825 <term>IFLT <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
826 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
827 <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
828 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
829 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
830 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
833 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
834 <term>IFLE <parameter>expr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
835 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
836 <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
837 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
838 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
839 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
842 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
843 <term>IFDEF <parameter>sym</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
844 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
845 <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
846 process, the conditional
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
847 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
848 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
849 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
850 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
851
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
852 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
853 <term>IFNDEF <parameter>sym</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
854 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
855 <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
856 process, the conditional
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
857 will be considered true.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
858 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
859 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
860 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
861
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
862 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
863 <term>ELSE</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
864 <listitem>
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 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
867 statements following will be assembled. If the preceding conditional at
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
868 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
869 Note that the preceding conditional might have been another ELSE statement
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
870 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
871 of LWASM.
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 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
874
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
875 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
876 <term>ENDC</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
877 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
878 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
879 This directive marks the end of a conditional construct. Every conditional
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
880 construct must end with an ENDC directive.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
881 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
882 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
883 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
884
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
885 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
886 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
887
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
888 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
889 <title>OS9 Target Directives</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
890
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
891 <para>This section includes directives that apply solely to the OS9
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
892 target.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
893
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
894 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
895
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
896 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
897 <term>OS9 <parameter>syscall</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
898 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
899 <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 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
902
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
903 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
904 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
905 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
906
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
907 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
908 <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
909 <listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
912 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
913 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
914 begin calcuating the module CRC.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
915
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
916 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
917
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
918 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
919
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
920 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
921 document since it is not a tutorial on OS9 module programming.
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 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
926 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
927
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
928 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
929 <term>EMOD</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
930 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
931 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
932
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
933 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
934 for the module.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
935
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
936 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
937 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
938
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
939 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
940 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
941
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
942 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
943 <title>Miscelaneous Directives</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
944
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
945 <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
946 categories.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
947
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
948 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
949
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
950 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
951 <term>INCLUDE <parameter>filename</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
952 <term>USE <parameter>filename</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
953
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
954 <listitem> <para> Include the contents of <parameter>filename</parameter> at
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
955 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
956 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
957 you must enclose <parameter>filename</parameter> in quotes.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
958 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
959
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
960 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
961 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
962 assemblers. It is recommended to use the INCLUDE variation.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
963
396
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
964 <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
965 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
966 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
967 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
968 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
969 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
970 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
971 </para>
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
972
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
973 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
974 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
975
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
976 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
977 <term>END <parameter>[expr]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
978 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
979 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
980 This directive causes the assembler to stop assembling immediately as though
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
981 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
982 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
983 other targets, specifying <parameter>expr</parameter> will cause an error.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
984 </para>
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 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
987
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
988 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
989 <term>ERROR <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
990 <listitem>
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 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
993 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
994 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
995 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
996 </para>
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
997 </listitem>
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
998 </varlistentry>
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
999
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
1000 <varlistentry>
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
1001 <term>WARNING <parameter>string</parameter></term>
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
1002 <listitem>
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 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
1005 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
1006 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
1007 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
1008 not cause any trouble.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1009 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1010 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1011 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1012
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1013 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1014 <term>.MODULE <parameter>string</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1015 <listitem>
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 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
1018 supports encoding a module name into it, <parameter>string</parameter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1019 will be used as the module name.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1020 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1021 <para>
396
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
1022 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
1023 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1024 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1025 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1026
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1027 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1028 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1029
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1030 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1031
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1032 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1033 <title>Macros</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1034 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1035 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
1036 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
1037 assembler directive. Defining a macro can be considered equivalent to adding
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1038 additional assembler directives.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1039 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1040 <para>Macros may accept parameters. These parameters are referenced within
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1041 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
1042 through ninth parameters. They may also be referenced by enclosing the
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1043 decimal parameter number in braces ("{num}"). These parameter references
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1044 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
1045 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
1046 Macro parameters are expanded everywhere on each source line. That means
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1047 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
1048 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
1049 when the macro is expanded.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1050 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1051 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1052 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
1053 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
1054 may be included in a macro parameter.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1055 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1056 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1057 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
1058 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
1059 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
1060 the reason.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1061
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1062 <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
1063 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
1064 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
1065 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
1066 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
1067 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
1068 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
1069 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
1070 an undefined symbol error or bizarre assembly results.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1071 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1072 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1073 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
1074 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
1075 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
1076 as a macro.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1077 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1078
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 Macros are defined only during the first pass. Macro expansion also
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1081 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
1082 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
1083 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1084
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1085 <para>The following directives are used when defining macros.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1086
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1087 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1088 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1089 <term><parameter>macroname</parameter> MACRO</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1090 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1091 <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
1092 <parameter>macroname</parameter>. If <parameter>macroname</parameter> already
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1093 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
1094 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
1095 be relied upon.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1096 </para>
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 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1099
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1100 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1101 <term>ENDM</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1102 <listitem>
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 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
1105 causes the assembler to resume interpreting source lines as normal.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1106 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1107 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1108 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1109
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1110 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1111
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1112 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1113 <title>Structures</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1114 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1115
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1116 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
1117 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
1118 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
1119 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
1120 There are two pseudo ops that are used for defining structures.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1121
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1122 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1123
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1124 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1125 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1126 <term><parameter>structname</parameter> STRUCT</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1127 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1128 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1129
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1130 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
1131 <parameter>structname</parameter>. Subsequent statements all form part of
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1132 the structure definition until the end of the structure is declared.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1133
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1134 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1135 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1136 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1137 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1138 <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
1139 <term>ENDS</term>
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1140 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1141 <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
1142 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
1143 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
1144 section instead of a structure.
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1145 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1146 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1147 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1148 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1149
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1150 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1151
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1152 Within a structure definition, only reservation pseudo ops are permitted.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1153 Anything else will cause an assembly error.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1154 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1155
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1156 <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
1157 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
1158 also contain fields that are themselves structures. See the example
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1159 below.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1160
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1161 <programlisting>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1162 tstruct2 STRUCT
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1163 f1 rmb 1
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1164 f2 rmb 1
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1165 ENDSTRUCT
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1166
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1167 tstruct STRUCT
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1168 field1 rmb 2
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1169 field2 rmb 3
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1170 field3 tstruct2
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1171 ENDSTRUCT
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1172
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1173 ORG $2000
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1174 var1 tstruct
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1175 var2 tstruct2
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1176 </programlisting>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1177
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1178 <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
1179 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
1180 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
1181 symbol name to the left of the dot.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1182
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1183 <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
1184 declared as a structure) using the special symbol sizeof{structname} where
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1185 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
1186 variable.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1187
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1188 <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
1189 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
1190 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
1191 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
1192 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
1193 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
1194 provide a listing. For instance, the above listing will create the
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1195 following symbols (symbol values in parentheses): tstruct2.f1 (0),
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1196 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1197 (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
1198 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1199 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1200 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
1201 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1202
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1203 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1204
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1205 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1206 <title>Object Files and Sections</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1207 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1208 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
1209 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
1210 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
1211 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
1212 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
1213 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
1214 symbol definitions, or other metadata that uses resources at assembly time.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1215 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
1216 for a mere mortal to find things in them.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1217 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1218
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1219 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1220 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
1221 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
1222 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
1223 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
1224 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
1225 places some restrictions on the code generated by the assembler. For
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1226 example, the assembler cannot generate direct page addressing for instructions
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1227 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
1228 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
1229 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
1230 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
1231 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
1232 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
1233 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
1234 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1235
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1236 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1237 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
1238 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
1239 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
1240 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
1241 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
1242 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
1243 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
1244 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1245
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1246 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1247 The existence of sections, however, raises a problem for symbols even
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1248 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
1249 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
1250 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
1251 with all the limitations that entails.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1252 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1253
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1254 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1255 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
1256 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
1257 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
1258 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
1259 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
1260 the starting address of the section's code, not the assembler.
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1263 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1264 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
1265 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
1266 considered local to the source file unless otherwise explicitly exported.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1267 Symbols referenced from external source files must be declared external,
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1268 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
1269 symbols are external.
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1272 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1273 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
1274 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
1275 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
1276 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
1277 Such sections are often known as BSS sections. LWASM supports generating
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1278 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
1279 symbols exported from that section and those symbols required to resolve
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1280 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
1281 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
1282 bytes to be output.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1283 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1284
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1285 <para>The following directives apply to section handling.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1286
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1287 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1288 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1289 <term>SECTION <parameter>name[,flags]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1290 <term>SECT <parameter>name[,flags]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1291 <term>.AREA <parameter>name[,flags]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1292 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1293 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1294 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
1295 considered part of the section <parameter>name</parameter>. A section name
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1296 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
1297 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
1298 However, <parameter>flags</parameter> may only be specified on the first
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1299 instance of the section.
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 <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
1302 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
1303 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
1304 bytes be permitted to be output.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1305 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1306 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
1307 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
1308 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
1309 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1310 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1311 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
1312 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
1313 it is recommended that all sections be explicitly closed.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1314 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1315 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1316 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1317
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1318 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1319 <term>ENDSECTION</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1320 <term>ENDSECT</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1321 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1322 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1323 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
1324 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
1325 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
1326 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
1327 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1328 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1329
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1330 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1331 <term><parameter>sym</parameter> EXTERN</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1332 <term><parameter>sym</parameter> EXTERNAL</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1333 <term><parameter>sym</parameter> IMPORT</term>
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1336 This directive defines <parameter>sym</parameter> as an external symbol.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1337 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
1338 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
1339 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
1340 optional when the assembler is instructed to assume that all undefined
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1341 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
1342 before the EXTERN directive, an error will occur.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1343 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1344 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1345 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1346
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1347 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1348 <term><parameter>sym</parameter> EXPORT</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1349 <term><parameter>sym</parameter> .GLOBL</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1350
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1351 <term>EXPORT <parameter>sym</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1352 <term>.GLOBL <parameter>sym</parameter></term>
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 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1355 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1356 This directive defines <parameter>sym</parameter> as an exported symbol.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1357 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
1358 definition of the exported symbol.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1359 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1360 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1361 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
1362 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
1363 take precedence over any operand that is present.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1364 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1365 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1366
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1367 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1368
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1369 <varlistentry>
396
62cb50c50976 Cosmetic updates to documentation; added warning pseudo op
lost@l-w.ca
parents: 331
diff changeset
1370 <term><parameter>sym</parameter> EXTDEP</term>
331
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1371 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1372
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1373 <para>This directive forces an external dependency on
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1374 <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
1375 this file.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1376
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1377 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1378 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1379 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1380
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1381 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1382
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1383 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1384 <title>Assembler Modes and Pragmas</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1385 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1386 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
1387 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
1388 they determine something absolute about the assembly process. These include
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1389 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
1390 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
1391 not portable between assemblers.
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1394 <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
1395 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
1396 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
1397 are as follows.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1398 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1399
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1400 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1401 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1402 <term>PRAGMA <parameter>pragma[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1403 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1404 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1405 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
1406 specified. Any unrecognized pragma will cause an assembly error. The new
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1407 pragmas will take effect immediately. This directive should be used when
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1408 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
1409 </para>
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 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1412
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1413 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1414 <term>*PRAGMA <parameter>pragma[,...]</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1415 <listitem>
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 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
1418 unrecognized or unsupported pragmas. This directive, by virtue of starting
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1419 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
1420 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
1421 for correct functioning of the code.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1422 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1423 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1424 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1425 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1426
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1427 <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
1428 The positive version enables the pragma while the negative version disables
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1429 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
1430 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
1431 listed below.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1432
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1433 <para>Pragmas are not case sensitive.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1434
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1435 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1436 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1437 <term>index0tonone</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1438 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1439 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1440 When in force, this pragma enables an optimization affecting indexed addressing
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1441 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
1442 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
1443 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
1444 of this optimization, it is enabled by default.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1445 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1446 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1447 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1448
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1449 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1450 <term>cescapes</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1451 <listitem>
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 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
1454 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
1455 spec is that unrecognized escape sequences will return either the character
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1456 immediately following the backslash or some undefined value. Do not rely
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1457 on the behaviour of undefined escape sequences.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1458 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1459 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1460 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1461
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1462 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1463 <term>importundefexport</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1464 <listitem>
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 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
1467 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
1468 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
1469 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
1470 the confusion this pragma can cause, it is disabled by default.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1471 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1472 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1473 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1474
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1475 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1476 <term>undefextern</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1477 <listitem>
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 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
1480 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
1481 automatically define it as an external symbol. This automatic definition will
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1482 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
1483 subsequently turned off. Because this behaviour would be potentially surprising,
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1484 this pragma defaults to off.
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1487 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
1488 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
1489 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
1490 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
1491 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
1492 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
1493 automatic external definition if there is already a locally defined symbol.)
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1494 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1495 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1496 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
1497 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
1498 for one or two files to use this pragma internally.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1499 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1500 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1501 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1502
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1503 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1504 <term>dollarlocal</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1505 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1506
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1507 <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
1508 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
1509 target.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1510
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1511 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1512 </varlistentry>
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 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1515 <term>dollarnotlocal</term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1516 <listitem>
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 <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
1519 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1520 "nodollarlocal" and "dollarnotlocal" are equivalent. </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1521
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1522 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1523 </varlistentry>
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 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1526
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1527 </section>
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 </chapter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1530
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1531 <chapter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1532 <title>LWLINK</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1533 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1534 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
1535 of the linker.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1536 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1537
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1538 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1539 <title>Command Line Options</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1540 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1541 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
1542 case. lwlink takes the following command line arguments.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1543 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1544 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1545 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1546 <term><option>--decb</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1547 <term><option>-b</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1548 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1549 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1550 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
1551 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1552 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1553 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1554
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1555 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1556 <term><option>--output=FILE</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1557 <term><option>-o FILE</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1558 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1559 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1560 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
1561 default is <option>a.out</option>.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1562 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1563 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1564 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1565
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>--format=TYPE</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1568 <term><option>-f TYPE</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 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
1572 and <option>raw</option>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1573 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1574 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1575 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1576
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1577 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1578 <term><option>--raw</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1579 <term><option>-r</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1580 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1581 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1582 This option specifies the raw output format.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1583 It is equivalent to <option>--format=raw</option>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1584 and <option>-f raw</option>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1585 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1586 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1589 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1590 <term><option>--script=FILE</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1591 <term><option>-s</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1592 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1593 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1594 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
1595 built in defaults.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1596 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1597 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1600 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1601 <term><option>--section-base=SECT=BASE</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1602 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1603 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1604 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
1605 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
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>--map=FILE</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1612 <term><option>-m FILE</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 will output a description of the link result to FILE.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1616 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1617 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1618 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1619
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1620 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1621 <term><option>--library=LIBSPEC</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1622 <term><option>-l LIBSPEC</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 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
1626 and ".a" appended.
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>--library-path=DIR</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1633 <term><option>-L DIR</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 Add DIR to the library search path.
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>--debug</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1643 <term><option>-d</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 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
1647 developers.
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>--help</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1654 <term><option>-?</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 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
1658 of each.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1659 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1660 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1661 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1662
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1663 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1664 <term><option>--usage</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 will display a usage summary
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1668 of each command line option.
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1674 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1675 <term><option>--version</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1676 <term><option>-V</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1677 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1678 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1679 This will display the version of LWLINK.
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 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1685
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1686 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1687 <title>Linker Operation</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1688
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1689 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1690
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1691 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
1692 into a single binary. Currently supported formats are the LWTOOLS object
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1693 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
1694 slightly different, linking can be conceptualized as the following steps.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1695
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1696 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1697
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1698 <orderedlist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1699 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1700 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1701 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
1702 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
1703 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
1704 binary.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1705 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1706 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1707
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1708 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1709 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1710 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
1711 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
1712 for each object at this time.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1713 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1714 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1715
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1716 <listitem>
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 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
1719 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
1720 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
1721 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
1722 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
1723 to the first instance of the section.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1724 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1725 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1726
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1729 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
1730 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
1731 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
1732 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
1733 incomplete reference can reference either a symbol internal to the object
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1734 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
1735 file.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1736 </para>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1739 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1740 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1741 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
1742 and actually constructs the binary.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1743 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1744 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1745 </orderedlist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1746
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1747 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1748
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1749 <section
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1750 <title>Linking Scripts</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1751 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1752 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
1753 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
1754 directives which are considered in the order they are encountered.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1755 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1756 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1757 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
1758 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
1759 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
1760 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
1761 an undefined effect.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1762 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1763
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 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
1766 are case sensitive although the hexadecimal numbers are not.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1767 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1768
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1769 <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
1770 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
1771 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
1772 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
1773 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
1774 bss will be matched.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1775 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1776
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1777 <para>The following directives are understood in a linker script.</para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1778 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1779 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1780 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1781 <listitem><para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1782
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1783 This causes the section <parameter>name</parameter> to load at
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1784 <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
1785 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
1786 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
1787 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
1788 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
1789 </para><para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1790 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
1791 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
1792 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
1793 everything out.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1794 </para></listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1795 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1796
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1797 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1798 <term>section <parameter>name</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1799 <listitem><para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1800
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1801 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
1802 section.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1803 </para></listitem></varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1804 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1805 <term>exec <parameter>addr or sym</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1806 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1807 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1808 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
1809 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
1810 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
1811 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
1812 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
1813 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
1814 that support this directive automatically starts at the beginning of the
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1815 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
1816 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1817 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1820 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1821 <term>pad <parameter>size</parameter></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1822 <listitem><para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1823 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
1824 <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
1825 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1826 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1827 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1828 </variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1829
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1830
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1831
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1832 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1833
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1834 </chapter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1835
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1836 <chapter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1837 <title>Libraries and LWAR</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1838
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1839 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1840 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
1841 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
1842 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
1843 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
1844 the command line except when resolving external references. External references
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1845 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
1846 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
1847 the command line occurs.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1848 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1849
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1850 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1851 The tool for creating these libary files is called LWAR.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1852 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1853
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1854 <section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1855 <title>Command Line Options</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1856 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1857 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
1858 case. The options lwar understands are listed below. For archive manipulation
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1859 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
1860 non-option arguments are the names of files to operate on.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1861 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1862
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1863 <variablelist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1864 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1865 <term><option>--add</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1866 <term><option>-a</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1867 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1868 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1869 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
1870 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
1871 to the end of the archive.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1872 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1873 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1874 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1875
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1876 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1877 <term><option>--create</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1878 <term><option>-c</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1879 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1880 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1881 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
1882 added to it. If the archive already exists, it is truncated.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1883 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1884 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1887 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1888 <term><option>--merge</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1889 <term><option>-m</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1890 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1891 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1892 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
1893 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
1894 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
1895 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1896 </listitem>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1899 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1900 <term><option>--list</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1901 <term><option>-l</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1902 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1903 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1904 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
1905 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1906 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1907 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1908
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1909 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1910 <term><option>--debug</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1911 <term><option>-d</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1912 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1913 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1914 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
1915 developers.
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>--help</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1922 <term><option>-?</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 provides a listing of command line options and a brief description
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1926 of each.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1927 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1928 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1929 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1930
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1931 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1932 <term><option>--usage</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 will display a usage summary
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1936 of each command line option.
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1942 <varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1943 <term><option>--version</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1944 <term><option>-V</option></term>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1945 <listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1946 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1947 This will display the version of LWLINK.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1948 of each.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1949 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1950 </listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1951 </varlistentry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1952
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1953 </section>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1954
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1955 </chapter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1956
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1957 <chapter id="objchap">
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1958 <title>Object Files</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1959 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1960 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
1961 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
1962 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
1963 documents the object file format.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1964 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1965
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1966 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1967 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
1968 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
1969 "local" symbols which may be used in calculating incomplete references. Each
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1970 section will obviously also contain the object code.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1971 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1972
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1973 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1974 Exported symbols must be completely resolved to an address within the
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1975 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
1976 rather than defined in terms of other symbols.</para>
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 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1979 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
1980 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
1981 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
1982 file are <code>4C574F424A313600</code>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1983 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1984
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 Each section has the following items in order:
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1989 <itemizedlist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1990 <listitem><para>section name</para></listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1991 <listitem><para>flags</para></listitem>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1992 <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
1993 <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
1994 <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
1995 <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
1996 </itemizedlist>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1997
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1998 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
1999 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
2000 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
2001 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
2002 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
2003 code is included in the object file.
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 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
2008 sections.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2009 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2010
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2011 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2012 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
2013 (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
2014 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
2015 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2016
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2017 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2018 Each entry in the incomplete references table consists of an expression
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2019 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
2020 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
2021 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
2022 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
2023 by a NULL expression (only an end of expression term).
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2024 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2025
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2026 <table frame="all"><title>Object File Term Types</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2027 <tgroup cols="2">
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2028 <thead>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2029 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2030 <entry>TERMTYPE</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2031 <entry>Meaning</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2032 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2033 </thead>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2034 <tbody>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2035 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2036 <entry>00</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2037 <entry>end of expression</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2038 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2039
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2040 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2041 <entry>01</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2042 <entry>integer (16 bit in big endian order follows)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2043 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2044 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2045 <entry>02</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2046 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2047 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2048
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2049 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2050 <entry>03</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2051 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2052 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2053
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2054 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2055 <entry>04</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2056 <entry>operator (1 byte operator number)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2057 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2058 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2059 <entry>05</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2060 <entry>section base address reference</entry>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2063 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2064 <entry>FF</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2065 <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
2066 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2067 </tbody>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2068 </tgroup>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2069 </table>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2070
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2071
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2072 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2073 External references are resolved using other object files while local
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2074 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
2075 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
2076 exported symbols or external references.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2077 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2078
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2079 <table frame="all"><title>Object File Operator Numbers</title>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2080 <tgroup cols="2">
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2081 <thead>
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 <entry>Number</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2084 <entry>Operator</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2085 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2086 </thead>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2087 <tbody>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2088 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2089 <entry>01</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2090 <entry>addition (+)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2091 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2092 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2093 <entry>02</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2094 <entry>subtraction (-)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2095 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2096 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2097 <entry>03</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2098 <entry>multiplication (*)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2099 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2100 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2101 <entry>04</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2102 <entry>division (/)</entry>
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 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2105 <entry>05</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2106 <entry>modulus (%)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2107 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2108 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2109 <entry>06</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2110 <entry>integer division (\) (same as division)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2111 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2112
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>07</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2115 <entry>bitwise and</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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2118 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2119 <entry>08</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2120 <entry>bitwise or</entry>
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
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2123 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2124 <entry>09</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2125 <entry>bitwise xor</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2126 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2127
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 <entry>0A</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2130 <entry>boolean and</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2131 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2132
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2133 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2134 <entry>0B</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2135 <entry>boolean or</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2136 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2137
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2138 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2139 <entry>0C</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2140 <entry>unary negation, 2's complement (-)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2141 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2142
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2143 <row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2144 <entry>0D</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2145 <entry>unary 1's complement (^)</entry>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2146 </row>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2147 </tbody>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2148 </tgroup>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2149 </table>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2150
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2151 <para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2152 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
2153 binary operators preceding the operator and the single operand for unary
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2154 operators preceding the operator.
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2155 </para>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2156
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2157 </chapter>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2158 </book>
ed3553296580 Port manual forward with corrections from Jason Law
lost
parents:
diff changeset
2159