Mercurial > hg-old > index.cgi

comparison doc/manual/x181.html @ 264:61d1db1dfe2a 2.6

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