Mercurial > hg-old > index.cgi

comparison doc/manual/x144.html @ 153:ffef3ea07399 2.1 2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Preparing for release
author lost
date Fri, 30 Jan 2009 04:32:55 +0000
parents
children
comparison
equal deleted inserted replaced
152:6bd4755d224f 153:ffef3ea07399
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&#62;</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 >