Mercurial > hg-old > index.cgi

comparison doc/manual/x146.html @ 285:9010796c6253 2.3 2.3.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Generated manual for distribution
author lost
date Fri, 24 Apr 2009 22:36:09 +0000
parents
children
comparison
equal deleted inserted replaced
284:a175fa4a0a9a 285:9010796c6253
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="x139.html"><LINK
18 REL="NEXT"
19 TITLE="Macros"
20 HREF="x378.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="x139.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="x378.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="AEN146"
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="AEN149"
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 >, .DB <CODE
102 CLASS="PARAMETER"
103 >expr[,...]</CODE
104 >, .BYTE <CODE
105 CLASS="PARAMETER"
106 >expr[,...]</CODE
107 ></DT
108 ><DD
109 ><P
110 >Include one or more constant bytes (separated by commas) in the output.</P
111 ></DD
112 ><DT
113 >FDB <CODE
114 CLASS="PARAMETER"
115 >expr[,...]</CODE
116 >, .DW <CODE
117 CLASS="PARAMETER"
118 >expr[,...]</CODE
119 >, .WORD <CODE
120 CLASS="PARAMETER"
121 >expr[,...]</CODE
122 ></DT
123 ><DD
124 ><P
125 >Include one or more words (separated by commas) in the output.</P
126 ></DD
127 ><DT
128 >FQB <CODE
129 CLASS="PARAMETER"
130 >expr[,...]</CODE
131 >, .QUAD <CODE
132 CLASS="PARAMETER"
133 >expr[,...]</CODE
134 >, .4BYTE <CODE
135 CLASS="PARAMETER"
136 >expr[,...]</CODE
137 ></DT
138 ><DD
139 ><P
140 >Include one or more double words (separated by commas) in the output.</P
141 ></DD
142 ><DT
143 >FCC <CODE
144 CLASS="PARAMETER"
145 >string</CODE
146 >, .ASCII <CODE
147 CLASS="PARAMETER"
148 >string</CODE
149 >, .STR <CODE
150 CLASS="PARAMETER"
151 >string</CODE
152 ></DT
153 ><DD
154 ><P
155 >Include a string of text in the output. The first character of the operand
156 is the delimiter which must appear as the last character and cannot appear
157 within the string. The string is included with no modifications&#62;</P
158 ></DD
159 ><DT
160 >FCN <CODE
161 CLASS="PARAMETER"
162 >string</CODE
163 >, .ASCIZ <CODE
164 CLASS="PARAMETER"
165 >string</CODE
166 >, .STRZ <CODE
167 CLASS="PARAMETER"
168 >string</CODE
169 ></DT
170 ><DD
171 ><P
172 >Include a NUL terminated string of text in the output. The first character of
173 the operand is the delimiter which must appear as the last character and
174 cannot appear within the string. A NUL byte is automatically appended to
175 the string.</P
176 ></DD
177 ><DT
178 >FCS <CODE
179 CLASS="PARAMETER"
180 >string</CODE
181 >, .ASCIS <CODE
182 CLASS="PARAMETER"
183 >string</CODE
184 >, .STRS <CODE
185 CLASS="PARAMETER"
186 >string</CODE
187 ></DT
188 ><DD
189 ><P
190 >Include a string of text in the output with bit 7 of the final byte set. The
191 first character of the operand is the delimiter which must appear as the last
192 character and cannot appear within the string.</P
193 ></DD
194 ><DT
195 >ZMB <CODE
196 CLASS="PARAMETER"
197 >expr</CODE
198 ></DT
199 ><DD
200 ><P
201 >Include a number of NUL bytes in the output. The number must be fully resolvable
202 during pass 1 of assembly so no forward or external references are permitted.</P
203 ></DD
204 ><DT
205 >ZMD <CODE
206 CLASS="PARAMETER"
207 >expr</CODE
208 ></DT
209 ><DD
210 ><P
211 >Include a number of zero 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.</P
214 ></DD
215 ><DT
216 >ZMQ <CODE
217 CLASS="PARAMETER"
218 >expr<CODE
219 CLASS="PARAMETER"
220 ></CODE
221 ></CODE
222 ></DT
223 ><DD
224 ><P
225 >Include a number of zero double-words in the output. The number must be fully
226 resolvable during pass 1 of assembly so no forward or external references are
227 permitted.</P
228 ></DD
229 ><DT
230 >RMB <CODE
231 CLASS="PARAMETER"
232 >expr</CODE
233 >, .BLKB <CODE
234 CLASS="PARAMETER"
235 >expr</CODE
236 >, .DS <CODE
237 CLASS="PARAMETER"
238 >expr</CODE
239 >, .RS <CODE
240 CLASS="PARAMETER"
241 >expr</CODE
242 ></DT
243 ><DD
244 ><P
245 >Reserve a number of bytes in the output. The number must be fully resolvable
246 during pass 1 of assembly so no forward or external references are permitted.
247 The value of the bytes is undefined.</P
248 ></DD
249 ><DT
250 >RMD <CODE
251 CLASS="PARAMETER"
252 >expr</CODE
253 ></DT
254 ><DD
255 ><P
256 >Reserve a number of words in the output. The number must be fully
257 resolvable during pass 1 of assembly so no forward or external references are
258 permitted. The value of the words is undefined.</P
259 ></DD
260 ><DT
261 >RMQ <CODE
262 CLASS="PARAMETER"
263 >expr</CODE
264 ></DT
265 ><DD
266 ><P
267 >Reserve a number of double-words in the output. The number must be fully
268 resolvable during pass 1 of assembly so no forward or external references are
269 permitted. The value of the double-words is undefined.</P
270 ></DD
271 ></DL
272 ></DIV
273 ></DIV
274 ><DIV
275 CLASS="SECTION"
276 ><H2
277 CLASS="SECTION"
278 ><A
279 NAME="AEN243"
280 >3.6.2. Address Definition</A
281 ></H2
282 ><P
283 >The directives in this section all control the addresses of symbols
284 or the assembly process itself.</P
285 ><P
286 ></P
287 ><DIV
288 CLASS="VARIABLELIST"
289 ><DL
290 ><DT
291 >ORG <CODE
292 CLASS="PARAMETER"
293 >expr</CODE
294 ></DT
295 ><DD
296 ><P
297 >Set the assembly address. The address must be fully resolvable on the
298 first pass so no external or forward references are permitted. ORG is not
299 permitted within sections when outputting to object files. For the DECB
300 target, each ORG directive after which output is generated will cause
301 a new preamble to be output. ORG is only used to determine the addresses
302 of symbols when the raw target is used.</P
303 ></DD
304 ><DT
305 ><CODE
306 CLASS="PARAMETER"
307 >sym</CODE
308 > EQU <CODE
309 CLASS="PARAMETER"
310 >expr</CODE
311 >, <CODE
312 CLASS="PARAMETER"
313 >sym</CODE
314 > = <CODE
315 CLASS="PARAMETER"
316 >expr</CODE
317 ></DT
318 ><DD
319 ><P
320 >Define the value of <CODE
321 CLASS="PARAMETER"
322 >sym</CODE
323 > to be <CODE
324 CLASS="PARAMETER"
325 >expr</CODE
326 >.</P
327 ></DD
328 ><DT
329 ><CODE
330 CLASS="PARAMETER"
331 >sym</CODE
332 > SET <CODE
333 CLASS="PARAMETER"
334 >expr</CODE
335 ></DT
336 ><DD
337 ><P
338 >Define the value of <CODE
339 CLASS="PARAMETER"
340 >sym</CODE
341 > to be <CODE
342 CLASS="PARAMETER"
343 >expr</CODE
344 >.
345 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
346 is used for all instances. Use of the symbol before the first SET statement
347 that sets its value is undefined.</P
348 ></DD
349 ><DT
350 >SETDP <CODE
351 CLASS="PARAMETER"
352 >expr</CODE
353 ></DT
354 ><DD
355 ><P
356 >Inform the assembler that it can assume the DP register contains
357 <CODE
358 CLASS="PARAMETER"
359 >expr</CODE
360 >. This directive is only advice to the assembler
361 to determine whether an address is in the direct page and has no effect
362 on the contents of the DP register. The value must be fully resolved during
363 the first assembly pass because it affects the sizes of subsequent instructions.</P
364 ><P
365 >This directive has no effect in the object file target.</P
366 ></DD
367 ><DT
368 >ALIGN <CODE
369 CLASS="PARAMETER"
370 >expr</CODE
371 ></DT
372 ><DD
373 ><P
374 >Force the current assembly address to be a multiple of <CODE
375 CLASS="PARAMETER"
376 >expr</CODE
377 >.
378 A series of NUL bytes is output to force the alignment, if required. The
379 alignment value must be fully resolved on the first pass because it affects
380 the addresses of subsquent instructions.</P
381 ><P
382 >This directive is not suitable for inclusion in the middle of actual
383 code. It is intended to appear where the bytes output will not be executed.</P
384 ></DD
385 ></DL
386 ></DIV
387 ></DIV
388 ><DIV
389 CLASS="SECTION"
390 ><H2
391 CLASS="SECTION"
392 ><A
393 NAME="AEN285"
394 >3.6.3. Conditional Assembly</A
395 ></H2
396 ><P
397 >Portions of the source code can be excluded or included based on conditions
398 known at assembly time. Conditionals can be nested arbitrarily deeply. The
399 directives associated with conditional assembly are described in this section.</P
400 ><P
401 >All conditionals must be fully bracketed. That is, every conditional
402 statement must eventually be followed by an ENDC at the same level of nesting.</P
403 ><P
404 >Conditional expressions are only evaluated on the first assembly pass.
405 It is not possible to game the assembly process by having a conditional
406 change its value between assembly passes. Thus there is not and never will
407 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P
408 ><P
409 ></P
410 ><DIV
411 CLASS="VARIABLELIST"
412 ><DL
413 ><DT
414 >IFEQ <CODE
415 CLASS="PARAMETER"
416 >expr</CODE
417 ></DT
418 ><DD
419 ><P
420 >If <CODE
421 CLASS="PARAMETER"
422 >expr</CODE
423 > evaluates to zero, the conditional
424 will be considered true.</P
425 ></DD
426 ><DT
427 >IFNE <CODE
428 CLASS="PARAMETER"
429 >expr</CODE
430 >, IF <CODE
431 CLASS="PARAMETER"
432 >expr</CODE
433 ></DT
434 ><DD
435 ><P
436 >If <CODE
437 CLASS="PARAMETER"
438 >expr</CODE
439 > evaluates to a non-zero value, the conditional
440 will be considered true.</P
441 ></DD
442 ><DT
443 >IFGT <CODE
444 CLASS="PARAMETER"
445 >expr</CODE
446 ></DT
447 ><DD
448 ><P
449 >If <CODE
450 CLASS="PARAMETER"
451 >expr</CODE
452 > evaluates to a value greater than zero, the conditional
453 will be considered true.</P
454 ></DD
455 ><DT
456 >IFGE <CODE
457 CLASS="PARAMETER"
458 >expr</CODE
459 ></DT
460 ><DD
461 ><P
462 >If <CODE
463 CLASS="PARAMETER"
464 >expr</CODE
465 > evaluates to a value greater than or equal to zero, the conditional
466 will be considered true.</P
467 ></DD
468 ><DT
469 >IFLT <CODE
470 CLASS="PARAMETER"
471 >expr</CODE
472 ></DT
473 ><DD
474 ><P
475 >If <CODE
476 CLASS="PARAMETER"
477 >expr</CODE
478 > evaluates to a value less than zero, the conditional
479 will be considered true.</P
480 ></DD
481 ><DT
482 >IFLE <CODE
483 CLASS="PARAMETER"
484 >expr</CODE
485 ></DT
486 ><DD
487 ><P
488 >If <CODE
489 CLASS="PARAMETER"
490 >expr</CODE
491 > evaluates to a value less than or equal to zero , the conditional
492 will be considered true.</P
493 ></DD
494 ><DT
495 >IFDEF <CODE
496 CLASS="PARAMETER"
497 >sym</CODE
498 ></DT
499 ><DD
500 ><P
501 >If <CODE
502 CLASS="PARAMETER"
503 >sym</CODE
504 > is defined at this point in the assembly
505 process, the conditional
506 will be considered true.</P
507 ></DD
508 ><DT
509 >IFNDEF <CODE
510 CLASS="PARAMETER"
511 >sym</CODE
512 ></DT
513 ><DD
514 ><P
515 >If <CODE
516 CLASS="PARAMETER"
517 >sym</CODE
518 > is not defined at this point in the assembly
519 process, the conditional
520 will be considered true.</P
521 ></DD
522 ><DT
523 >ELSE</DT
524 ><DD
525 ><P
526 >If the preceding conditional at the same level of nesting was false, the
527 statements following will be assembled. If the preceding conditional at
528 the same level was true, the statements following will not be assembled.
529 Note that the preceding conditional might have been another ELSE statement
530 although this behaviour is not guaranteed to be supported in future versions
531 of LWASM.</P
532 ></DD
533 ><DT
534 >ENDC</DT
535 ><DD
536 ><P
537 >This directive marks the end of a conditional construct. Every conditional
538 construct must end with an ENDC directive.</P
539 ></DD
540 ></DL
541 ></DIV
542 ></DIV
543 ><DIV
544 CLASS="SECTION"
545 ><H2
546 CLASS="SECTION"
547 ><A
548 NAME="AEN349"
549 >3.6.4. Miscelaneous Directives</A
550 ></H2
551 ><P
552 >This section includes directives that do not fit into the other
553 categories.</P
554 ><P
555 ></P
556 ><DIV
557 CLASS="VARIABLELIST"
558 ><DL
559 ><DT
560 >INCLUDE <CODE
561 CLASS="PARAMETER"
562 >filename</CODE
563 ></DT
564 ><DD
565 ><P
566 >Include the contents of <CODE
567 CLASS="PARAMETER"
568 >filename</CODE
569 > at this point in
570 the assembly as though it were a part of the file currently being processed.
571 Note that whitespace cannot appear in the name of the file.</P
572 ></DD
573 ><DT
574 >END <CODE
575 CLASS="PARAMETER"
576 >[expr]</CODE
577 ></DT
578 ><DD
579 ><P
580 >This directive causes the assembler to stop assembling immediately as though
581 it ran out of input. For the DECB target only, <CODE
582 CLASS="PARAMETER"
583 >expr</CODE
584 >
585 can be used to set the execution address of the resulting binary. For all
586 other targets, specifying <CODE
587 CLASS="PARAMETER"
588 >expr</CODE
589 > will cause an error.</P
590 ></DD
591 ><DT
592 >ERROR <CODE
593 CLASS="PARAMETER"
594 >string</CODE
595 ></DT
596 ><DD
597 ><P
598 >Causes a custom error message to be printed at this line. This will cause
599 assembly to fail. This directive is most useful inside conditional constructs
600 to cause assembly to fail if some condition that is known bad happens.</P
601 ></DD
602 ><DT
603 >.MODULE <CODE
604 CLASS="PARAMETER"
605 >string</CODE
606 ></DT
607 ><DD
608 ><P
609 >This directive is ignored for most output targets. If the output target
610 supports encoding a module name into it, <CODE
611 CLASS="PARAMETER"
612 >string</CODE
613 >
614 will be used as the module name.</P
615 ><P
616 >As of version 2.2, no supported output targets support this directive.</P
617 ></DD
618 ></DL
619 ></DIV
620 ></DIV
621 ></DIV
622 ><DIV
623 CLASS="NAVFOOTER"
624 ><HR
625 ALIGN="LEFT"
626 WIDTH="100%"><TABLE
627 SUMMARY="Footer navigation table"
628 WIDTH="100%"
629 BORDER="0"
630 CELLPADDING="0"
631 CELLSPACING="0"
632 ><TR
633 ><TD
634 WIDTH="33%"
635 ALIGN="left"
636 VALIGN="top"
637 ><A
638 HREF="x139.html"
639 ACCESSKEY="P"
640 >Prev</A
641 ></TD
642 ><TD
643 WIDTH="34%"
644 ALIGN="center"
645 VALIGN="top"
646 ><A
647 HREF="index.html"
648 ACCESSKEY="H"
649 >Home</A
650 ></TD
651 ><TD
652 WIDTH="33%"
653 ALIGN="right"
654 VALIGN="top"
655 ><A
656 HREF="x378.html"
657 ACCESSKEY="N"
658 >Next</A
659 ></TD
660 ></TR
661 ><TR
662 ><TD
663 WIDTH="33%"
664 ALIGN="left"
665 VALIGN="top"
666 >Numbers and Expressions</TD
667 ><TD
668 WIDTH="34%"
669 ALIGN="center"
670 VALIGN="top"
671 ><A
672 HREF="c35.html"
673 ACCESSKEY="U"
674 >Up</A
675 ></TD
676 ><TD
677 WIDTH="33%"
678 ALIGN="right"
679 VALIGN="top"
680 >Macros</TD
681 ></TR
682 ></TABLE
683 ></DIV
684 ></BODY
685 ></HTML
686 >