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