Mercurial > hg-old > index.cgi

comparison doc/manual/x173.html @ 272:d5392bb5da3c 2.5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added generated files
author lost
date Sun, 16 Aug 2009 17:16:49 +0000
parents
children
comparison
equal deleted inserted replaced
271:3b793ba7a6c6 272:d5392bb5da3c
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="c43.html"><LINK
15 REL="PREVIOUS"
16 TITLE="Numbers and Expressions"
17 HREF="x165.html"><LINK
18 REL="NEXT"
19 TITLE="Macros"
20 HREF="x445.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="x165.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="x445.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="AEN173"
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="AEN176"
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 ><DT
272 >INCLUDEBIN <CODE
273 CLASS="PARAMETER"
274 >filename</CODE
275 ></DT
276 ><DD
277 ><P
278 >Treat the contents of <CODE
279 CLASS="PARAMETER"
280 >filename</CODE
281 > as a string of bytes to
282 be included literally at the current assembly point. This has the same effect
283 as converting the file contents to a series of FCB statements and including
284 those at the current assembly point.</P
285 ></DD
286 ></DL
287 ></DIV
288 ></DIV
289 ><DIV
290 CLASS="SECTION"
291 ><H2
292 CLASS="SECTION"
293 ><A
294 NAME="AEN276"
295 >3.6.2. Address Definition</A
296 ></H2
297 ><P
298 >The directives in this section all control the addresses of symbols
299 or the assembly process itself.</P
300 ><P
301 ></P
302 ><DIV
303 CLASS="VARIABLELIST"
304 ><DL
305 ><DT
306 >ORG <CODE
307 CLASS="PARAMETER"
308 >expr</CODE
309 ></DT
310 ><DD
311 ><P
312 >Set the assembly address. The address must be fully resolvable on the
313 first pass so no external or forward references are permitted. ORG is not
314 permitted within sections when outputting to object files. For the DECB
315 target, each ORG directive after which output is generated will cause
316 a new preamble to be output. ORG is only used to determine the addresses
317 of symbols when the raw target is used.</P
318 ></DD
319 ><DT
320 ><CODE
321 CLASS="PARAMETER"
322 >sym</CODE
323 > EQU <CODE
324 CLASS="PARAMETER"
325 >expr</CODE
326 >, <CODE
327 CLASS="PARAMETER"
328 >sym</CODE
329 > = <CODE
330 CLASS="PARAMETER"
331 >expr</CODE
332 ></DT
333 ><DD
334 ><P
335 >Define the value of <CODE
336 CLASS="PARAMETER"
337 >sym</CODE
338 > to be <CODE
339 CLASS="PARAMETER"
340 >expr</CODE
341 >.</P
342 ></DD
343 ><DT
344 ><CODE
345 CLASS="PARAMETER"
346 >sym</CODE
347 > SET <CODE
348 CLASS="PARAMETER"
349 >expr</CODE
350 ></DT
351 ><DD
352 ><P
353 >Define the value of <CODE
354 CLASS="PARAMETER"
355 >sym</CODE
356 > to be <CODE
357 CLASS="PARAMETER"
358 >expr</CODE
359 >.
360 Unlike EQU, SET permits symbols to be defined multiple times as long as SET
361 is used for all instances. Use of the symbol before the first SET statement
362 that sets its value is undefined.</P
363 ></DD
364 ><DT
365 >SETDP <CODE
366 CLASS="PARAMETER"
367 >expr</CODE
368 ></DT
369 ><DD
370 ><P
371 >Inform the assembler that it can assume the DP register contains
372 <CODE
373 CLASS="PARAMETER"
374 >expr</CODE
375 >. This directive is only advice to the assembler
376 to determine whether an address is in the direct page and has no effect
377 on the contents of the DP register. The value must be fully resolved during
378 the first assembly pass because it affects the sizes of subsequent instructions.</P
379 ><P
380 >This directive has no effect in the object file target.</P
381 ></DD
382 ><DT
383 >ALIGN <CODE
384 CLASS="PARAMETER"
385 >expr</CODE
386 >[,<CODE
387 CLASS="PARAMETER"
388 >value</CODE
389 >]</DT
390 ><DD
391 ><P
392 >Force the current assembly address to be a multiple of
393 <CODE
394 CLASS="PARAMETER"
395 >expr</CODE
396 >. If <CODE
397 CLASS="PARAMETER"
398 >value</CODE
399 > is not
400 specified, a series of NUL bytes is output to force the alignment, if
401 required. Otherwise, the low order 8 bits of <CODE
402 CLASS="PARAMETER"
403 >value</CODE
404 >
405 will be used as the fill. The alignment value must be fully resolved on the
406 first pass because it affects the addresses of subsquent instructions.
407 However, <CODE
408 CLASS="PARAMETER"
409 >value</CODE
410 > may include forward references; as
411 long as it resolves to a constant for the second pass, the value will be
412 accepted.</P
413 ><P
414 >Unless <CODE
415 CLASS="PARAMETER"
416 >value</CODE
417 > is specified as something like $12,
418 this directive is not suitable for inclusion in the middle of actual code.
419 The default padding value is $00 which is intended to be used within data
420 blocks. </P
421 ></DD
422 ></DL
423 ></DIV
424 ></DIV
425 ><DIV
426 CLASS="SECTION"
427 ><H2
428 CLASS="SECTION"
429 ><A
430 NAME="AEN323"
431 >3.6.3. Conditional Assembly</A
432 ></H2
433 ><P
434 >Portions of the source code can be excluded or included based on conditions
435 known at assembly time. Conditionals can be nested arbitrarily deeply. The
436 directives associated with conditional assembly are described in this section.</P
437 ><P
438 >All conditionals must be fully bracketed. That is, every conditional
439 statement must eventually be followed by an ENDC at the same level of nesting.</P
440 ><P
441 >Conditional expressions are only evaluated on the first assembly pass.
442 It is not possible to game the assembly process by having a conditional
443 change its value between assembly passes. Thus there is not and never will
444 be any equivalent of IFP1 or IFP2 as provided by other assemblers.</P
445 ><P
446 ></P
447 ><DIV
448 CLASS="VARIABLELIST"
449 ><DL
450 ><DT
451 >IFEQ <CODE
452 CLASS="PARAMETER"
453 >expr</CODE
454 ></DT
455 ><DD
456 ><P
457 >If <CODE
458 CLASS="PARAMETER"
459 >expr</CODE
460 > evaluates to zero, the conditional
461 will be considered true.</P
462 ></DD
463 ><DT
464 >IFNE <CODE
465 CLASS="PARAMETER"
466 >expr</CODE
467 >, IF <CODE
468 CLASS="PARAMETER"
469 >expr</CODE
470 ></DT
471 ><DD
472 ><P
473 >If <CODE
474 CLASS="PARAMETER"
475 >expr</CODE
476 > evaluates to a non-zero value, the conditional
477 will be considered true.</P
478 ></DD
479 ><DT
480 >IFGT <CODE
481 CLASS="PARAMETER"
482 >expr</CODE
483 ></DT
484 ><DD
485 ><P
486 >If <CODE
487 CLASS="PARAMETER"
488 >expr</CODE
489 > evaluates to a value greater than zero, the conditional
490 will be considered true.</P
491 ></DD
492 ><DT
493 >IFGE <CODE
494 CLASS="PARAMETER"
495 >expr</CODE
496 ></DT
497 ><DD
498 ><P
499 >If <CODE
500 CLASS="PARAMETER"
501 >expr</CODE
502 > evaluates to a value greater than or equal to zero, the conditional
503 will be considered true.</P
504 ></DD
505 ><DT
506 >IFLT <CODE
507 CLASS="PARAMETER"
508 >expr</CODE
509 ></DT
510 ><DD
511 ><P
512 >If <CODE
513 CLASS="PARAMETER"
514 >expr</CODE
515 > evaluates to a value less than zero, the conditional
516 will be considered true.</P
517 ></DD
518 ><DT
519 >IFLE <CODE
520 CLASS="PARAMETER"
521 >expr</CODE
522 ></DT
523 ><DD
524 ><P
525 >If <CODE
526 CLASS="PARAMETER"
527 >expr</CODE
528 > evaluates to a value less than or equal to zero , the conditional
529 will be considered true.</P
530 ></DD
531 ><DT
532 >IFDEF <CODE
533 CLASS="PARAMETER"
534 >sym</CODE
535 ></DT
536 ><DD
537 ><P
538 >If <CODE
539 CLASS="PARAMETER"
540 >sym</CODE
541 > is defined at this point in the assembly
542 process, the conditional
543 will be considered true.</P
544 ></DD
545 ><DT
546 >IFNDEF <CODE
547 CLASS="PARAMETER"
548 >sym</CODE
549 ></DT
550 ><DD
551 ><P
552 >If <CODE
553 CLASS="PARAMETER"
554 >sym</CODE
555 > is not defined at this point in the assembly
556 process, the conditional
557 will be considered true.</P
558 ></DD
559 ><DT
560 >ELSE</DT
561 ><DD
562 ><P
563 >If the preceding conditional at the same level of nesting was false, the
564 statements following will be assembled. If the preceding conditional at
565 the same level was true, the statements following will not be assembled.
566 Note that the preceding conditional might have been another ELSE statement
567 although this behaviour is not guaranteed to be supported in future versions
568 of LWASM.</P
569 ></DD
570 ><DT
571 >ENDC</DT
572 ><DD
573 ><P
574 >This directive marks the end of a conditional construct. Every conditional
575 construct must end with an ENDC directive.</P
576 ></DD
577 ></DL
578 ></DIV
579 ></DIV
580 ><DIV
581 CLASS="SECTION"
582 ><H2
583 CLASS="SECTION"
584 ><A
585 NAME="AEN387"
586 >3.6.4. OS9 Target Directives</A
587 ></H2
588 ><P
589 >This section includes directives that apply solely to the OS9
590 target.</P
591 ><P
592 ></P
593 ><DIV
594 CLASS="VARIABLELIST"
595 ><DL
596 ><DT
597 >OS9 <CODE
598 CLASS="PARAMETER"
599 >syscall</CODE
600 ></DT
601 ><DD
602 ><P
603 >&#13;This directive generates a call to the specified system call. <CODE
604 CLASS="PARAMETER"
605 >syscall</CODE
606 > may be an arbitrary expression.&#13;</P
607 ></DD
608 ><DT
609 >MOD <CODE
610 CLASS="PARAMETER"
611 >size</CODE
612 >,<CODE
613 CLASS="PARAMETER"
614 >name</CODE
615 >,<CODE
616 CLASS="PARAMETER"
617 >type</CODE
618 >,<CODE
619 CLASS="PARAMETER"
620 >flags</CODE
621 >,<CODE
622 CLASS="PARAMETER"
623 >execoff</CODE
624 >,<CODE
625 CLASS="PARAMETER"
626 >datasize</CODE
627 ></DT
628 ><DD
629 ><P
630 >&#13;This tells LWASM that the beginning of the actual module is here. It will
631 generate a module header based on the parameters specified. It will also
632 begin calcuating the module CRC.&#13;</P
633 ><P
634 >&#13;The precise meaning of the various parameters is beyond the scope of this
635 document since it is not a tutorial on OS9 module programming.&#13;</P
636 ></DD
637 ><DT
638 >EMOD</DT
639 ><DD
640 ><P
641 >&#13;This marks the end of a module and causes LWASM to emit the calculated CRC
642 for the module.&#13;</P
643 ></DD
644 ></DL
645 ></DIV
646 ></DIV
647 ><DIV
648 CLASS="SECTION"
649 ><H2
650 CLASS="SECTION"
651 ><A
652 NAME="AEN412"
653 >3.6.5. Miscelaneous Directives</A
654 ></H2
655 ><P
656 >This section includes directives that do not fit into the other
657 categories.</P
658 ><P
659 ></P
660 ><DIV
661 CLASS="VARIABLELIST"
662 ><DL
663 ><DT
664 >INCLUDE <CODE
665 CLASS="PARAMETER"
666 >filename</CODE
667 >, USE <CODE
668 CLASS="PARAMETER"
669 >filename</CODE
670 ></DT
671 ><DD
672 ><P
673 > Include the contents of <CODE
674 CLASS="PARAMETER"
675 >filename</CODE
676 > at
677 this point in the assembly as though it were a part of the file currently
678 being processed. Note that if whitespace appears in the name of the file,
679 you must enclose <CODE
680 CLASS="PARAMETER"
681 >filename</CODE
682 > in quotes.</P
683 ><P
684 >Note that the USE variation is provided only for compatibility with other
685 assemblers. It is recommended to use the INCLUDE variation.</P
686 ></DD
687 ><DT
688 >END <CODE
689 CLASS="PARAMETER"
690 >[expr]</CODE
691 ></DT
692 ><DD
693 ><P
694 >This directive causes the assembler to stop assembling immediately as though
695 it ran out of input. For the DECB target only, <CODE
696 CLASS="PARAMETER"
697 >expr</CODE
698 >
699 can be used to set the execution address of the resulting binary. For all
700 other targets, specifying <CODE
701 CLASS="PARAMETER"
702 >expr</CODE
703 > will cause an error.</P
704 ></DD
705 ><DT
706 >ERROR <CODE
707 CLASS="PARAMETER"
708 >string</CODE
709 ></DT
710 ><DD
711 ><P
712 >Causes a custom error message to be printed at this line. This will cause
713 assembly to fail. This directive is most useful inside conditional constructs
714 to cause assembly to fail if some condition that is known bad happens.</P
715 ></DD
716 ><DT
717 >.MODULE <CODE
718 CLASS="PARAMETER"
719 >string</CODE
720 ></DT
721 ><DD
722 ><P
723 >This directive is ignored for most output targets. If the output target
724 supports encoding a module name into it, <CODE
725 CLASS="PARAMETER"
726 >string</CODE
727 >
728 will be used as the module name.</P
729 ><P
730 >As of version 2.2, no supported output targets support this directive.</P
731 ></DD
732 ></DL
733 ></DIV
734 ></DIV
735 ></DIV
736 ><DIV
737 CLASS="NAVFOOTER"
738 ><HR
739 ALIGN="LEFT"
740 WIDTH="100%"><TABLE
741 SUMMARY="Footer navigation table"
742 WIDTH="100%"
743 BORDER="0"
744 CELLPADDING="0"
745 CELLSPACING="0"
746 ><TR
747 ><TD
748 WIDTH="33%"
749 ALIGN="left"
750 VALIGN="top"
751 ><A
752 HREF="x165.html"
753 ACCESSKEY="P"
754 >Prev</A
755 ></TD
756 ><TD
757 WIDTH="34%"
758 ALIGN="center"
759 VALIGN="top"
760 ><A
761 HREF="index.html"
762 ACCESSKEY="H"
763 >Home</A
764 ></TD
765 ><TD
766 WIDTH="33%"
767 ALIGN="right"
768 VALIGN="top"
769 ><A
770 HREF="x445.html"
771 ACCESSKEY="N"
772 >Next</A
773 ></TD
774 ></TR
775 ><TR
776 ><TD
777 WIDTH="33%"
778 ALIGN="left"
779 VALIGN="top"
780 >Numbers and Expressions</TD
781 ><TD
782 WIDTH="34%"
783 ALIGN="center"
784 VALIGN="top"
785 ><A
786 HREF="c43.html"
787 ACCESSKEY="U"
788 >Up</A
789 ></TD
790 ><TD
791 WIDTH="33%"
792 ALIGN="right"
793 VALIGN="top"
794 >Macros</TD
795 ></TR
796 ></TABLE
797 ></DIV
798 ></BODY
799 ></HTML
800 >