153
|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
|
|
2 <HTML
|
|
3 ><HEAD
|
|
4 ><TITLE
|
|
5 >Assembler Directives</TITLE
|
|
6 ><META
|
|
7 NAME="GENERATOR"
|
|
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
|
|
9 REL="HOME"
|
|
10 TITLE="LW Tool Chain"
|
|
11 HREF="index.html"><LINK
|
|
12 REL="UP"
|
|
13 TITLE="LWASM"
|
|
14 HREF="c35.html"><LINK
|
|
15 REL="PREVIOUS"
|
|
16 TITLE="Numbers and Expressions"
|
|
17 HREF="x137.html"><LINK
|
|
18 REL="NEXT"
|
|
19 TITLE="Macros"
|
|
20 HREF="x339.html"></HEAD
|
|
21 ><BODY
|
|
22 CLASS="SECTION"
|
|
23 BGCOLOR="#FFFFFF"
|
|
24 TEXT="#000000"
|
|
25 LINK="#0000FF"
|
|
26 VLINK="#840084"
|
|
27 ALINK="#0000FF"
|
|
28 ><DIV
|
|
29 CLASS="NAVHEADER"
|
|
30 ><TABLE
|
|
31 SUMMARY="Header navigation table"
|
|
32 WIDTH="100%"
|
|
33 BORDER="0"
|
|
34 CELLPADDING="0"
|
|
35 CELLSPACING="0"
|
|
36 ><TR
|
|
37 ><TH
|
|
38 COLSPAN="3"
|
|
39 ALIGN="center"
|
|
40 >LW Tool Chain</TH
|
|
41 ></TR
|
|
42 ><TR
|
|
43 ><TD
|
|
44 WIDTH="10%"
|
|
45 ALIGN="left"
|
|
46 VALIGN="bottom"
|
|
47 ><A
|
|
48 HREF="x137.html"
|
|
49 ACCESSKEY="P"
|
|
50 >Prev</A
|
|
51 ></TD
|
|
52 ><TD
|
|
53 WIDTH="80%"
|
|
54 ALIGN="center"
|
|
55 VALIGN="bottom"
|
|
56 >Chapter 3. LWASM</TD
|
|
57 ><TD
|
|
58 WIDTH="10%"
|
|
59 ALIGN="right"
|
|
60 VALIGN="bottom"
|
|
61 ><A
|
|
62 HREF="x339.html"
|
|
63 ACCESSKEY="N"
|
|
64 >Next</A
|
|
65 ></TD
|
|
66 ></TR
|
|
67 ></TABLE
|
|
68 ><HR
|
|
69 ALIGN="LEFT"
|
|
70 WIDTH="100%"></DIV
|
|
71 ><DIV
|
|
72 CLASS="SECTION"
|
|
73 ><H1
|
|
74 CLASS="SECTION"
|
|
75 ><A
|
|
76 NAME="AEN144"
|
|
77 >3.6. Assembler Directives</A
|
|
78 ></H1
|
|
79 ><P
|
|
80 >Various directives can be used to control the behaviour of the
|
|
81 assembler or to include non-code/data in the resulting output. Those directives
|
|
82 that are not described in detail in other sections of this document are
|
|
83 described below.</P
|
|
84 ><DIV
|
|
85 CLASS="SECTION"
|
|
86 ><H2
|
|
87 CLASS="SECTION"
|
|
88 ><A
|
|
89 NAME="AEN147"
|
|
90 >3.6.1. Data Directives</A
|
|
91 ></H2
|
|
92 ><P
|
|
93 ></P
|
|
94 ><DIV
|
|
95 CLASS="VARIABLELIST"
|
|
96 ><DL
|
|
97 ><DT
|
|
98 >FCB <CODE
|
|
99 CLASS="PARAMETER"
|
|
100 >expr[,...]</CODE
|
|
101 ></DT
|
|
102 ><DD
|
|
103 ><P
|
|
104 >Include one or more constant bytes (separated by commas) in the output.</P
|
|
105 ></DD
|
|
106 ><DT
|
|
107 >FDB <CODE
|
|
108 CLASS="PARAMETER"
|
|
109 >expr[,...]</CODE
|
|
110 ></DT
|
|
111 ><DD
|
|
112 ><P
|
|
113 >Include one or more words (separated by commas) in the output.</P
|
|
114 ></DD
|
|
115 ><DT
|
|
116 >FQB <CODE
|
|
117 CLASS="PARAMETER"
|
|
118 >expr[,...]</CODE
|
|
119 ></DT
|
|
120 ><DD
|
|
121 ><P
|
|
122 >Include one or more double words (separated by commas) in the output.</P
|
|
123 ></DD
|
|
124 ><DT
|
|
125 >FCC <CODE
|
|
126 CLASS="PARAMETER"
|
|
127 >string</CODE
|
|
128 ></DT
|
|
129 ><DD
|
|
130 ><P
|
|
131 >Include a string of text in the output. The first character of the operand
|
|
132 is the delimiter which must appear as the last character and cannot appear
|
|
133 within the string. The string is included with no modifications></P
|
|
134 ></DD
|
|
135 ><DT
|
|
136 >FCN <CODE
|
|
137 CLASS="PARAMETER"
|
|
138 >string</CODE
|
|
139 ></DT
|
|
140 ><DD
|
|
141 ><P
|
|
142 >Include a NUL terminated string of text in the output. The first character of
|
|
143 the operand is the delimiter which must appear as the last character and
|
|
144 cannot appear within the string. A NUL byte is automatically appended to
|
|
145 the string.</P
|
|
146 ></DD
|
|
147 ><DT
|
|
148 >FCS <CODE
|
|
149 CLASS="PARAMETER"
|
|
150 >string</CODE
|
|
151 ></DT
|
|
152 ><DD
|
|
153 ><P
|
|
154 >Include a string of text in the output with bit 7 of the final byte set. The
|
|
155 first character of the operand is the delimiter which must appear as the last
|
|
156 character and cannot appear within the string.</P
|
|
157 ></DD
|
|
158 ><DT
|
|
159 >ZMB <CODE
|
|
160 CLASS="PARAMETER"
|
|
161 >expr</CODE
|
|
162 ></DT
|
|
163 ><DD
|
|
164 ><P
|
|
165 >Include a number of NUL bytes in the output. The number must be fully resolvable
|
|
166 during pass 1 of assembly so no forward or external references are permitted.</P
|
|
167 ></DD
|
|
168 ><DT
|
|
169 >ZMD <CODE
|
|
170 CLASS="PARAMETER"
|
|
171 >expr</CODE
|
|
172 ></DT
|
|
173 ><DD
|
|
174 ><P
|
|
175 >Include a number of zero words in the output. The number must be fully
|
|
176 resolvable during pass 1 of assembly so no forward or external references are
|
|
177 permitted.</P
|
|
178 ></DD
|
|
179 ><DT
|
|
180 >ZMQ <CODE
|
|
181 CLASS="PARAMETER"
|
|
182 >expr<CODE
|
|
183 CLASS="PARAMETER"
|
|
184 ></CODE
|
|
185 ></CODE
|
|
186 ></DT
|
|
187 ><DD
|
|
188 ><P
|
|
189 >Include a number of zero double-words in the output. The number must be fully
|
|
190 resolvable during pass 1 of assembly so no forward or external references are
|
|
191 permitted.</P
|
|
192 ></DD
|
|
193 ><DT
|
|
194 >RMB <CODE
|
|
195 CLASS="PARAMETER"
|
|
196 >expr</CODE
|
|
197 ></DT
|
|
198 ><DD
|
|
199 ><P
|
|
200 >Reserve a number of bytes in the output. The number must be fully resolvable
|
|
201 during pass 1 of assembly so no forward or external references are permitted.
|
|
202 The value of the bytes is undefined.</P
|
|
203 ></DD
|
|
204 ><DT
|
|
205 >RMD <CODE
|
|
206 CLASS="PARAMETER"
|
|
207 >expr</CODE
|
|
208 ></DT
|
|
209 ><DD
|
|
210 ><P
|
|
211 >Reserve a number of words in the output. The number must be fully
|
|
212 resolvable during pass 1 of assembly so no forward or external references are
|
|
213 permitted. The value of the words is undefined.</P
|
|
214 ></DD
|
|
215 ><DT
|
|
216 >RMQ <CODE
|
|
217 CLASS="PARAMETER"
|
|
218 >expr</CODE
|
|
219 ></DT
|
|
220 ><DD
|
|
221 ><P
|
|
222 >Reserve a number of double-words in the output. The number must be fully
|
|
223 resolvable during pass 1 of assembly so no forward or external references are
|
|
224 permitted. The value of the double-words is undefined.</P
|
|
225 ></DD
|
|
226 ></DL
|
|
227 ></DIV
|
|
228 ></DIV
|
|
229 ><DIV
|
|
230 CLASS="SECTION"
|
|
231 ><H2
|
|
232 CLASS="SECTION"
|
|
233 ><A
|
|
234 NAME="AEN211"
|
|
235 >3.6.2. Address Definition</A
|
|
236 ></H2
|
|
237 ><P
|
|
238 >The directives in this section all control the addresses of symbols
|
|
239 or the assembly process itself.</P
|
|
240 ><P
|
|
241 ></P
|
|
242 ><DIV
|
|
243 CLASS="VARIABLELIST"
|
|
244 ><DL
|
|
245 ><DT
|
|
246 >ORG <CODE
|
|
247 CLASS="PARAMETER"
|
|
248 >expr</CODE
|
|
249 ></DT
|
|
250 ><DD
|
|
251 ><P
|
|
252 >Set the assembly address. The address must be fully resolvable on the
|
|
253 first pass so no external or forward references are permitted. ORG is not
|
|
254 permitted within sections when outputting to object files. For the DECB
|
|
255 target, each ORG directive after which output is generated will cause
|
|
256 a new preamble to be output. ORG is only used to determine the addresses
|
|
257 of symbols when the raw target is used.</P
|
|
258 ></DD
|
|
259 ><DT
|
|
260 ><CODE
|
|
261 CLASS="PARAMETER"
|
|
262 >sym</CODE
|
|
263 > EQU <CODE
|
|
264 CLASS="PARAMETER"
|
|
265 >expr</CODE
|
|
266 >, <CODE
|
|
267 CLASS="PARAMETER"
|
|
268 >sym</CODE
|
|
269 > = <CODE
|
|
270 CLASS="PARAMETER"
|
|
271 >expr</CODE
|
|
272 ></DT
|
|
273 ><DD
|
|
274 ><P
|
|
275 >Define the value of <CODE
|
|
276 CLASS="PARAMETER"
|
|
277 >sym</CODE
|
|
278 > to be <CODE
|
|
279 CLASS="PARAMETER"
|
|
280 >expr</CODE
|
|
281 >.</P
|
|
282 ></DD
|
|
283 ><DT
|
|
284 ><CODE
|
|
285 CLASS="PARAMETER"
|
|
286 >sym</CODE
|
|
287 > SET <CODE
|
|
288 CLASS="PARAMETER"
|
|
289 >expr</CODE
|
|
290 ></DT
|
|
291 ><DD
|
|
292 ><P
|
|
293 >Define the value of <CODE
|
|
294 CLASS="PARAMETER"
|
|
295 >sym</CODE
|
|
296 > to be <CODE
|
|
297 CLASS="PARAMETER"
|
|
298 >expr</CODE
|
|
299 >.
|
|
300 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
|
|
301 is used for all instances. Use of the symbol before the first SET statement
|
|
302 that sets its value is undefined.</P
|
|
303 ></DD
|
|
304 ><DT
|
|
305 >SETDP <CODE
|
|
306 CLASS="PARAMETER"
|
|
307 >expr</CODE
|
|
308 ></DT
|
|
309 ><DD
|
|
310 ><P
|
|
311 >Inform the assembler that it can assume the DP register contains
|
|
312 <CODE
|
|
313 CLASS="PARAMETER"
|
|
314 >expr</CODE
|
|
315 >. This directive is only advice to the assembler
|
|
316 to determine whether an address is in the direct page and has no effect
|
|
317 on the contents of the DP register. The value must be fully resolved during
|
|
318 the first assembly pass because it affects the sizes of subsequent instructions.</P
|
|
319 ><P
|
|
320 >This directive has no effect in the object file target.</P
|
|
321 ></DD
|
|
322 ><DT
|
|
323 >ALIGN <CODE
|
|
324 CLASS="PARAMETER"
|
|
325 >expr</CODE
|
|
326 ></DT
|
|
327 ><DD
|
|
328 ><P
|
|
329 >Force the current assembly address to be a multiple of <CODE
|
|
330 CLASS="PARAMETER"
|
|
331 >expr</CODE
|
|
332 >.
|
|
333 A series of NUL bytes is output to force the alignment, if required. The
|
|
334 alignment value must be fully resolved on the first pass because it affects
|
|
335 the addresses of subsquent instructions.</P
|
|
336 ><P
|
|
337 >This directive is not suitable for inclusion in the middle of actual
|
|
338 code. It is intended to appear where the bytes output will not be executed.</P
|
|
339 ></DD
|
|
340 ></DL
|
|
341 ></DIV
|
|
342 ></DIV
|
|
343 ><DIV
|
|
344 CLASS="SECTION"
|
|
345 ><H2
|
|
346 CLASS="SECTION"
|
|
347 ><A
|
|
348 NAME="AEN253"
|
|
349 >3.6.3. Conditional Assembly</A
|
|
350 ></H2
|
|
351 ><P
|
|
352 >Portions of the source code can be excluded or included based on conditions
|
|
353 known at assembly time. Conditionals can be nested arbitrarily deeply. The
|
|
354 directives associated with conditional assembly are described in this section.</P
|
|
355 ><P
|
|
356 >All conditionals must be fully bracketed. That is, every conditional
|
|
357 statement must eventually be followed by an ENDC at the same level of nesting.</P
|
|
358 ><P
|
|
359 >Conditional expressions are only evaluated on the first assembly pass.
|
|
360 It is not possible to game the assembly process by having a conditional
|
|
361 change its value between assembly passes. Thus there is not and never will
|
|
362 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P
|
|
363 ><P
|
|
364 ></P
|
|
365 ><DIV
|
|
366 CLASS="VARIABLELIST"
|
|
367 ><DL
|
|
368 ><DT
|
|
369 >IFEQ <CODE
|
|
370 CLASS="PARAMETER"
|
|
371 >expr</CODE
|
|
372 ></DT
|
|
373 ><DD
|
|
374 ><P
|
|
375 >If <CODE
|
|
376 CLASS="PARAMETER"
|
|
377 >expr</CODE
|
|
378 > evaluates to zero, the conditional
|
|
379 will be considered true.</P
|
|
380 ></DD
|
|
381 ><DT
|
|
382 >IFNE <CODE
|
|
383 CLASS="PARAMETER"
|
|
384 >expr</CODE
|
|
385 >, IF <CODE
|
|
386 CLASS="PARAMETER"
|
|
387 >expr</CODE
|
|
388 ></DT
|
|
389 ><DD
|
|
390 ><P
|
|
391 >If <CODE
|
|
392 CLASS="PARAMETER"
|
|
393 >expr</CODE
|
|
394 > evaluates to a non-zero value, the conditional
|
|
395 will be considered true.</P
|
|
396 ></DD
|
|
397 ><DT
|
|
398 >IFGT <CODE
|
|
399 CLASS="PARAMETER"
|
|
400 >expr</CODE
|
|
401 ></DT
|
|
402 ><DD
|
|
403 ><P
|
|
404 >If <CODE
|
|
405 CLASS="PARAMETER"
|
|
406 >expr</CODE
|
|
407 > evaluates to a value greater than zero, the conditional
|
|
408 will be considered true.</P
|
|
409 ></DD
|
|
410 ><DT
|
|
411 >IFGE <CODE
|
|
412 CLASS="PARAMETER"
|
|
413 >expr</CODE
|
|
414 ></DT
|
|
415 ><DD
|
|
416 ><P
|
|
417 >If <CODE
|
|
418 CLASS="PARAMETER"
|
|
419 >expr</CODE
|
|
420 > evaluates to a value greater than or equal to zero, the conditional
|
|
421 will be considered true.</P
|
|
422 ></DD
|
|
423 ><DT
|
|
424 >IFLT <CODE
|
|
425 CLASS="PARAMETER"
|
|
426 >expr</CODE
|
|
427 ></DT
|
|
428 ><DD
|
|
429 ><P
|
|
430 >If <CODE
|
|
431 CLASS="PARAMETER"
|
|
432 >expr</CODE
|
|
433 > evaluates to a value less than zero, the conditional
|
|
434 will be considered true.</P
|
|
435 ></DD
|
|
436 ><DT
|
|
437 >IFLE <CODE
|
|
438 CLASS="PARAMETER"
|
|
439 >expr</CODE
|
|
440 ></DT
|
|
441 ><DD
|
|
442 ><P
|
|
443 >If <CODE
|
|
444 CLASS="PARAMETER"
|
|
445 >expr</CODE
|
|
446 > evaluates to a value less than or equal to zero , the conditional
|
|
447 will be considered true.</P
|
|
448 ></DD
|
|
449 ><DT
|
|
450 >IFDEF <CODE
|
|
451 CLASS="PARAMETER"
|
|
452 >sym</CODE
|
|
453 ></DT
|
|
454 ><DD
|
|
455 ><P
|
|
456 >If <CODE
|
|
457 CLASS="PARAMETER"
|
|
458 >sym</CODE
|
|
459 > is defined at this point in the assembly
|
|
460 process, the conditional
|
|
461 will be considered true.</P
|
|
462 ></DD
|
|
463 ><DT
|
|
464 >IFNDEF <CODE
|
|
465 CLASS="PARAMETER"
|
|
466 >sym</CODE
|
|
467 ></DT
|
|
468 ><DD
|
|
469 ><P
|
|
470 >If <CODE
|
|
471 CLASS="PARAMETER"
|
|
472 >sym</CODE
|
|
473 > is not defined at this point in the assembly
|
|
474 process, the conditional
|
|
475 will be considered true.</P
|
|
476 ></DD
|
|
477 ><DT
|
|
478 >ELSE</DT
|
|
479 ><DD
|
|
480 ><P
|
|
481 >If the preceding conditional at the same level of nesting was false, the
|
|
482 statements following will be assembled. If the preceding conditional at
|
|
483 the same level was true, the statements following will not be assembled.
|
|
484 Note that the preceding conditional might have been another ELSE statement
|
|
485 although this behaviour is not guaranteed to be supported in future versions
|
|
486 of LWASM.</P
|
|
487 ></DD
|
|
488 ><DT
|
|
489 >ENDC</DT
|
|
490 ><DD
|
|
491 ><P
|
|
492 >This directive marks the end of a conditional construct. Every conditional
|
|
493 construct must end with an ENDC directive.</P
|
|
494 ></DD
|
|
495 ></DL
|
|
496 ></DIV
|
|
497 ></DIV
|
|
498 ><DIV
|
|
499 CLASS="SECTION"
|
|
500 ><H2
|
|
501 CLASS="SECTION"
|
|
502 ><A
|
|
503 NAME="AEN317"
|
|
504 >3.6.4. Miscelaneous Directives</A
|
|
505 ></H2
|
|
506 ><P
|
|
507 >This section includes directives that do not fit into the other
|
|
508 categories.</P
|
|
509 ><P
|
|
510 ></P
|
|
511 ><DIV
|
|
512 CLASS="VARIABLELIST"
|
|
513 ><DL
|
|
514 ><DT
|
|
515 >INCLUDE <CODE
|
|
516 CLASS="PARAMETER"
|
|
517 >filename</CODE
|
|
518 ></DT
|
|
519 ><DD
|
|
520 ><P
|
|
521 >Include the contents of <CODE
|
|
522 CLASS="PARAMETER"
|
|
523 >filename</CODE
|
|
524 > at this point in
|
|
525 the assembly as though it were a part of the file currently being processed.
|
|
526 Note that whitespace cannot appear in the name of the file.</P
|
|
527 ></DD
|
|
528 ><DT
|
|
529 >END <CODE
|
|
530 CLASS="PARAMETER"
|
|
531 >[expr]</CODE
|
|
532 ></DT
|
|
533 ><DD
|
|
534 ><P
|
|
535 >This directive causes the assembler to stop assembling immediately as though
|
|
536 it ran out of input. For the DECB target only, <CODE
|
|
537 CLASS="PARAMETER"
|
|
538 >expr</CODE
|
|
539 >
|
|
540 can be used to set the execution address of the resulting binary. For all
|
|
541 other targets, specifying <CODE
|
|
542 CLASS="PARAMETER"
|
|
543 >expr</CODE
|
|
544 > will cause an error.</P
|
|
545 ></DD
|
|
546 ><DT
|
|
547 >ERROR <CODE
|
|
548 CLASS="PARAMETER"
|
|
549 >string</CODE
|
|
550 ></DT
|
|
551 ><DD
|
|
552 ><P
|
|
553 >Causes a custom error message to be printed at this line. This will cause
|
|
554 assembly to fail. This directive is most useful inside conditional constructs
|
|
555 to cause assembly to fail if some condition that is known bad happens.</P
|
|
556 ></DD
|
|
557 ></DL
|
|
558 ></DIV
|
|
559 ></DIV
|
|
560 ></DIV
|
|
561 ><DIV
|
|
562 CLASS="NAVFOOTER"
|
|
563 ><HR
|
|
564 ALIGN="LEFT"
|
|
565 WIDTH="100%"><TABLE
|
|
566 SUMMARY="Footer navigation table"
|
|
567 WIDTH="100%"
|
|
568 BORDER="0"
|
|
569 CELLPADDING="0"
|
|
570 CELLSPACING="0"
|
|
571 ><TR
|
|
572 ><TD
|
|
573 WIDTH="33%"
|
|
574 ALIGN="left"
|
|
575 VALIGN="top"
|
|
576 ><A
|
|
577 HREF="x137.html"
|
|
578 ACCESSKEY="P"
|
|
579 >Prev</A
|
|
580 ></TD
|
|
581 ><TD
|
|
582 WIDTH="34%"
|
|
583 ALIGN="center"
|
|
584 VALIGN="top"
|
|
585 ><A
|
|
586 HREF="index.html"
|
|
587 ACCESSKEY="H"
|
|
588 >Home</A
|
|
589 ></TD
|
|
590 ><TD
|
|
591 WIDTH="33%"
|
|
592 ALIGN="right"
|
|
593 VALIGN="top"
|
|
594 ><A
|
|
595 HREF="x339.html"
|
|
596 ACCESSKEY="N"
|
|
597 >Next</A
|
|
598 ></TD
|
|
599 ></TR
|
|
600 ><TR
|
|
601 ><TD
|
|
602 WIDTH="33%"
|
|
603 ALIGN="left"
|
|
604 VALIGN="top"
|
|
605 >Numbers and Expressions</TD
|
|
606 ><TD
|
|
607 WIDTH="34%"
|
|
608 ALIGN="center"
|
|
609 VALIGN="top"
|
|
610 ><A
|
|
611 HREF="c35.html"
|
|
612 ACCESSKEY="U"
|
|
613 >Up</A
|
|
614 ></TD
|
|
615 ><TD
|
|
616 WIDTH="33%"
|
|
617 ALIGN="right"
|
|
618 VALIGN="top"
|
|
619 >Macros</TD
|
|
620 ></TR
|
|
621 ></TABLE
|
|
622 ></DIV
|
|
623 ></BODY
|
|
624 ></HTML
|
|
625 > |