466
|
1 <appendix>
|
|
2 <title>Relocating Macro Assembler Reference</title>
|
|
3 <para>
|
468
|
4 This appendix gives a summary of the operation of the "Relocating
|
|
5 Macro Assembler" (named c.asm as distributed with the C Compiler).
|
|
6 This appendix and the example assembly source files supplied with
|
|
7 the C compiler should provide the basic information on how to use the
|
|
8 "Relocating Macro Assembler" to create relocatable-object format
|
|
9 files (ROF). It is further assumed that you are familiar with the
|
|
10 6809 instruction set and mnemonics. See the Microware Relocating
|
|
11 Assembler Manual for a more detailed description. The main function
|
|
12 of this appendix is to enable the reader to understand the output
|
|
13 produced by c.asm. The Relocating Macro Assembler allows programs
|
|
14 to be compiled separately and then linked together, and it also
|
|
15 allows macros to be defined within programs.
|
|
16 </para>
|
|
17 <para>
|
|
18 Differences between the Relocating Macro Assembler (RMA) and the
|
|
19 Microware Interactive Assembler (MIA):
|
|
20 </para>
|
|
21 <blockquote>
|
|
22 <para>
|
|
23 RMA does not have an interactive mode. Only a disk file is
|
|
24 allowed as input.
|
466
|
25 </para>
|
468
|
26 <para>
|
|
27 RMA output is an ROF file. The ROF file must be processed by
|
|
28 the linker to produce an executable OS9 memory module. The
|
|
29 layout of the ROF file is described later.
|
|
30 </para>
|
|
31 <para>
|
|
32 RMA has a number of new directives to control the placement of
|
|
33 code and data in the executable module. Since RMA does not
|
|
34 produce memory modules, the MIA directives "mod" and "emod" are
|
|
35 not present. Instead, new directives PSECT and VSECT control
|
|
36 the allocation of code and data areas by the linker.
|
|
37 </para>
|
|
38 <para>
|
|
39 RMA has no equivalent to the MIA "setdp" directive. Data (and
|
|
40 DP) allocation is handled by the linker.
|
|
41 </para>
|
|
42 </blockquote>
|
|
43 <section>
|
530
|
44 <title>Symbolic Names</title>
|
468
|
45 <para>
|
|
46 A symbolic name is valid if it consists of from one to nine
|
|
47 uppercase or lowercase characters, decimal digits or the characters
|
|
48 "$", "_", "." or "@". RMA does not fold lowercase letters to
|
|
49 uppercase. The names "Hi.you" and "HI.YOU" are distinct names.
|
|
50 </para>
|
|
51 </section>
|
530
|
52
|
|
53 <section>
|
|
54 <title>Label field</title>
|
|
55 <para>
|
|
56 If a symbolic name in the label field of a source statement is
|
|
57 followed by a <quote>:</quote> (colon), the name will be known
|
|
58 <emphasis>globally</emphasis> (by all modules linked together).
|
|
59 If no colon appears, the name will be known only in the PSECT
|
|
60 in which it was defined. PSECT will be described later.
|
|
61 </para>
|
|
62 </section>
|
|
63
|
|
64 <section>
|
|
65 <title>Undefined names</title>
|
|
66 <para>
|
651
|
67 If a symbolic name is used in an expression and hasn't been defined,
|
|
68 RMA assumes the name is external to the PSECT. RMA will record
|
|
69 information about the reference so the linker can adjust the operand
|
|
70 accordingly. External names cannot appear in operand expressions
|
|
71 for assembler directives.
|
530
|
72 </para>
|
|
73 </section>
|
|
74
|
|
75 <section>
|
|
76 <title>Listing format</title>
|
651
|
77 <programlisting>
|
|
78 00098 0032 59 + rolb
|
|
79 00117 0045=17ffb8 label lbsr _dmove Comment
|
|
80 ^ ^ ^^ ^ ^ ^ ^ ^
|
|
81 | | || | | | | Start of comment
|
|
82 | | || | | | Start of operand
|
|
83 | | || | | Start of mnemonic
|
|
84 | | || | Start of label
|
|
85 | | || A "+" indicates a line generated by a macro
|
|
86 | | || expansion.
|
|
87 | | |Start of object code bytes.
|
|
88 | | An "=" here indicates that the operand contains an
|
|
89 | | external reference.
|
|
90 | Location counter value
|
|
91 Line number.
|
|
92 </programlisting>
|
530
|
93 </section>
|
|
94
|
|
95 <section>
|
|
96 <title>Section Location Counters</title>
|
|
97 <para>
|
653
|
98 Each section contains the following location counters:
|
530
|
99 </para>
|
653
|
100 <variablelist termlength="5">
|
|
101 <varlistentry><term>PSECT</term>
|
|
102 <listitem><literallayout>instruction location counter</literallayout>
|
|
103 </listitem>
|
|
104 </varlistentry>
|
|
105 <varlistentry><term>VSECT</term>
|
|
106 <listitem><literallayout>initialized direct page location counter
|
|
107 non-initialized direct page location counter
|
|
108 initialized data location counter
|
|
109 non-initialized data location counter</literallayout>
|
|
110 </listitem>
|
|
111 </varlistentry>
|
|
112 <varlistentry><term>CSECT</term>
|
|
113 <listitem><literallayout>base offset counter</literallayout>
|
|
114 </listitem>
|
|
115 </varlistentry>
|
|
116 </variablelist>
|
530
|
117 </section>
|
|
118
|
|
119 <section>
|
|
120 <title>Section Directives</title>
|
|
121 <para>
|
653
|
122 RMA contains 3 section directives. PSECT indicates to the linker
|
|
123 the beginning of a relocatable-object-format file (<acronym>ROF</acronym>) and
|
|
124 initializes the instruction and data location counters and assembles
|
|
125 code into the <acronym>ROF</acronym> object code area. VSECT causes RMA to change to
|
|
126 the data location counters and place any generated code into the
|
|
127 appropiate <acronym>ROF</acronym> data area. CSECT initializes a base value for
|
|
128 assigning offsets to symbols. The end of these sections is indicated by the
|
|
129 ENDSECT directive.
|
530
|
130 </para>
|
653
|
131 <para>
|
|
132 The source statements placed in a particular section cause the
|
|
133 linker to perform a function appropiate for the statement.
|
|
134 Therefore, the mnemonics allowed within a section are restricted as
|
|
135 follows:
|
|
136 </para>
|
|
137 <itemizedlist>
|
|
138 <listitem>
|
|
139 <para>
|
|
140 The mnemonics are allowed inside or outside any section: nam,
|
|
141 opt, ttl, pag, spc, use, fail, rept, endr, ifeq, ifne, iflt,
|
|
142 ifle, ifge, ifgt, ifpl, endc, else, equ, set, macro, endm,
|
|
143 csect, and endsect.
|
|
144 </para>
|
|
145 </listitem>
|
|
146 <listitem>
|
|
147 <para>
|
|
148 Within a CSECT: rmb
|
|
149 </para>
|
|
150 </listitem>
|
|
151 <listitem>
|
|
152 <para>
|
|
153 Within a PSECT: any 6809 instruction mnemonic, fcc, fdb,fcs,
|
|
154 fcb, rzb, vsect, endsect, os9 and end.
|
|
155 </para>
|
|
156 </listitem>
|
|
157 <listitem>
|
|
158 <para>
|
|
159 Within a VSECT: rmb, fcc, fdb, fcs, fcb, rzb and endsect.
|
|
160 </para>
|
|
161 </listitem>
|
|
162 </itemizedlist>
|
530
|
163 <section>
|
|
164 <title>PSECT Directive</title>
|
|
165 <para>
|
563
|
166 The main difference between PSECT and MOD is that MOD sets up
|
|
167 information for OS-9 and PSECT sets up information for the
|
|
168 linker (c.link in the C compiler).
|
530
|
169 </para>
|
563
|
170 <informalexample>
|
|
171 <para>
|
|
172 PSECT {name,typelang,attrrev,edition,stacksize,entrypoint}
|
|
173 </para>
|
|
174 <informaltable frame="none">
|
|
175 <tgroup cols="2">
|
633
|
176 <colspec colwidth="0.8in"/>
|
|
177 <colspec colwidth="3.2in"/>
|
563
|
178 <tbody>
|
|
179 <row>
|
|
180 <entry>name</entry>
|
|
181 <entry>Up to 20 bytes (any printable character except space
|
|
182 or comma) for a name to be used by the linker to
|
|
183 identify this PSECT. This name need not be distinct
|
|
184 from all other PSECTs linked together, but it helps
|
|
185 to identify PSECTs the linker has a problem with if
|
|
186 the names are different.</entry>
|
|
187 </row>
|
|
188 <row>
|
|
189 <entry>typelang</entry>
|
653
|
190 <entry>byte expression for the executable module type/language
|
|
191 byte. If this PSECT is not a "mainline"
|
|
192 (a module that has been designed to be forked to) module
|
|
193 this byte must be zero.</entry>
|
563
|
194 </row>
|
|
195 <row>
|
|
196 <entry>attrrev</entry>
|
653
|
197 <entry>byte expression for executable module attribute/revision byte.</entry>
|
563
|
198 </row>
|
|
199 <row>
|
|
200 <entry>edition</entry>
|
653
|
201 <entry>byte expression for executable module edition byte.</entry>
|
563
|
202 </row>
|
|
203 <row>
|
|
204 <entry>stacksize</entry>
|
653
|
205 <entry>word expression estimating the amount of stack storage
|
|
206 required by this psect. The linker totals this
|
|
207 value in all PSECTs to appear in the executable module and
|
|
208 adds this value to any data storage requirement
|
|
209 for the entire program.</entry>
|
563
|
210 </row>
|
|
211 <row>
|
|
212 <entry>entrypoint</entry>
|
|
213 <entry>word expression entrypoint offset for this PSECT.
|
|
214 If the PSECT is not a mainline odule, this should
|
|
215 be set to zero.</entry>
|
|
216 </row>
|
|
217 </tbody>
|
|
218 </tgroup>
|
|
219 </informaltable>
|
|
220 </informalexample>
|
653
|
221 <para>
|
|
222 PSECT must have either no operand list or an operand list
|
|
223 containing a name and five expressions. If no operand list is
|
|
224 provided, the PSECT name defaults to "program" and all other
|
|
225 expressions to zero. The can only be one PSECT per assembly
|
|
226 language file.
|
|
227 </para>
|
|
228 <para>
|
|
229 The PSECT directive initializes all counter orgs and marks the
|
|
230 start of the program module. No VSECT data reservations or
|
|
231 object code may appear before or after the PSECT/ENDSECT block.
|
|
232 </para>
|
|
233 <para>
|
|
234 Example:
|
|
235 <programlisting>
|
|
236 psect myprog,Prgrm+Objct,Reent+1,Edit,0,progent
|
|
237 psect another_prog,0,0,0,0,0
|
|
238 </programlisting>
|
|
239 </para>
|
530
|
240 </section>
|
|
241
|
|
242 <section>
|
|
243 <title>VSECT Directive</title>
|
|
244 <para>
|
653
|
245 VSECT {DP}
|
|
246 </para>
|
|
247 <para>
|
|
248 The VSECT directive causes RMA to change to the data location
|
|
249 counters. If DP appears after VSECT, the direct page counters are
|
|
250 used, otherwise the non-direct page data is used. The RMB directive
|
|
251 within this section reserves the specified number of bytes in the
|
|
252 appropiate uninitialized data section. The fcc, fdb, fcs, fcb and
|
|
253 rzb (reserve zeroed bytes) directives place data into the
|
|
254 appropiate initialized data section. If an operand for fdb or fcb
|
|
255 contains an external reference, this information is placed in the
|
|
256 external reference part of the ROF to be adjusted at link or
|
|
257 execution time. ENDSECT marks the end of the VSECT block. Any
|
|
258 number of VSECT blocks can appear within a PSECT. Note, however,
|
|
259 that the data location counters maintain their values between one
|
|
260 VSECT block and the next. Since the linker handles the actual data
|
|
261 allocation, there is no facility provided to adjust the data
|
|
262 location counters.
|
530
|
263 </para>
|
|
264 </section>
|
|
265
|
|
266 <section>
|
|
267 <title>CSECT Directive</title>
|
|
268 <para>
|
653
|
269 CSECT {expression}
|
|
270 </para>
|
|
271 <para>
|
|
272 The CSECT directive provides a means for assigning consecutive
|
|
273 offsets to labels without resorting to EQUs. If the expression is
|
|
274 present, the CSECT base counter is set to that value, otherwise it
|
|
275 is set to zero.
|
530
|
276 </para>
|
|
277 </section>
|
|
278
|
|
279 <section>
|
|
280 <title>RZB statement</title>
|
|
281 <para>
|
653
|
282 RZB <expression>
|
|
283 </para>
|
|
284 <para>
|
|
285 The reserve zeroed bytes pseudo-instruction generates sequences of
|
|
286 zero bytes in the code or initialized data sections, the number of
|
|
287 which is specified by the expression.
|
530
|
288 </para>
|
|
289 </section>
|
|
290 </section>
|
|
291
|
|
292 <section>
|
|
293 <title>Comparison Between Assembly Programs for the Microware Interactive Assember
|
|
294 and the Relocating Macro Assembler</title>
|
|
295 <para>
|
|
296 The following two program examples simply fork a BASIC09. The
|
|
297 purpose of the examples are to show some of the differences in the
|
|
298 new relocating assembler. The differences are apparent.
|
|
299 </para>
|
|
300 <programlisting>
|
|
301 * this program forks a basic09
|
|
302 ifp1
|
|
303 use ..../defs/os9defs.a
|
|
304 endc
|
|
305
|
653
|
306 PRGRM equ $10
|
|
307 OBJCT equ $01
|
530
|
308
|
653
|
309 stk equ 200
|
|
310 psect rmatest,$11,$81,0,stk,entry
|
|
311
|
|
312 name fcs /basic09/
|
|
313 prm fcb $D
|
|
314 prmsize equ *-prm
|
|
315
|
|
316 entry leax name,pcr
|
|
317 leau prm,pcr
|
|
318 ldy #prmsize
|
|
319 lda #PRGRM+OBJCT
|
|
320 clrb
|
|
321 os9 F$FORK
|
|
322 os9 F$WAIT
|
|
323 os9 F$EXIT
|
|
324 endsect
|
530
|
325 </programlisting>
|
|
326 <section>
|
|
327 <title>Macro Interactive Assembler Source</title>
|
|
328 <programlisting>
|
|
329 ifp1
|
|
330 use defsfile
|
653
|
331 endc
|
530
|
332
|
653
|
333 mod siz,prnam,type,revs,start,size
|
|
334 prnam fcs /testshell/
|
|
335 type set prgm+objct
|
|
336 revs set reent+1
|
|
337
|
|
338 rmb 250
|
|
339 rmb 200
|
|
340 name fcs /basic09/
|
|
341 prm fcb $D
|
530
|
342 prmsize equ *-prm
|
653
|
343 size equ .
|
|
344 start equ *
|
|
345 leax name,pcr
|
|
346 leau prm,pcr
|
|
347 ldy #prmsize
|
|
348 lda #PRGRM+OBJCT
|
|
349 clrb
|
|
350 os9 F$FORK
|
|
351 os9 F$WAIT
|
|
352 os9 F$EXIT
|
|
353 emod
|
530
|
354 siz equ
|
|
355 </programlisting>
|
|
356 </section>
|
|
357 </section>
|
|
358
|
|
359 <section>
|
|
360 <title>Introduction to Macros</title>
|
|
361 <para>
|
653
|
362 In programming applications it is frequently necessary to use a
|
|
363 repeated sequence or pattern of instructions in many different
|
|
364 places in a program. For example, suppose a group of program
|
|
365 statements creates a file a number of times throughout the program.
|
|
366 The code might look like the following statements:
|
|
367 </para>
|
|
368 <screen>
|
|
369 leax name,pcr
|
|
370 lda $02
|
|
371 ldb $03
|
|
372 os9 I$CREATE
|
|
373 </screen>
|
|
374 <para>
|
|
375 The sequence must be replicated each time that a new file is
|
|
376 created. A macro assembler eliminates the need for coding duplicate
|
|
377 statement patterns by allowing the programmer to define macro
|
|
378 instructions that are equivalent to longer code sequences.
|
|
379 </para>
|
|
380 <para>
|
|
381 When a macro is called, it is the same as calling a subrouting to
|
|
382 perform a defined function. A macro produces in-line code that is
|
|
383 inserted into the normal flow of the program beginning at the
|
|
384 location of the macro call. The statements that may be generated by
|
|
385 a macro are generally unrestricted, and the statements may contain
|
|
386 substitutable arguments.
|
530
|
387 </para>
|
|
388 </section>
|
|
389
|
|
390 <section>
|
|
391 <title>Operations</title>
|
|
392
|
|
393 <section>
|
|
394 <title>Macro Definition</title>
|
|
395 <para>
|
653
|
396 A macro definition consists of three sections:
|
|
397 </para>
|
|
398 <screen>
|
|
399 <Label> MACRO /* macro header */
|
|
400 . /* <Label> is the name of the macro */
|
|
401 .
|
|
402 body /* macro body */
|
|
403 .
|
|
404 .
|
|
405 ENDM /* macro terminator */
|
|
406 </screen>
|
|
407 <orderedlist numeration="arabic" spacing="compact">
|
|
408 <listitem>
|
|
409 <para>The macro header - assigns a name to the macro</para>
|
|
410 </listitem>
|
|
411 <listitem>
|
|
412 <para>The body - contains the macro statements</para>
|
|
413 </listitem>
|
|
414 <listitem>
|
|
415 <para>The terminator - indicates the end of the macro</para>
|
|
416 </listitem>
|
|
417 </orderedlist>
|
|
418 <para>
|
|
419 A macro can have up to nine arguments (\1 to \9) in the operand
|
|
420 fields. The arguments are used to refer to symbols, registers, etc.
|
|
421 </para>
|
|
422 <para>
|
|
423 The following macro below could represent the file creation pattern:
|
|
424 </para>
|
|
425 <programlisting>
|
|
426 CREATE MACRO
|
|
427 leax \1,pcr
|
|
428 lda $\2
|
|
429 ldb $\3
|
|
430 os9 I$CREATE
|
|
431 ENDM
|
|
432 </programlisting>
|
|
433 <para>
|
|
434 Calls can be made to create files with different names, access
|
|
435 modes, and attributes as follows:
|
|
436 </para>
|
|
437 <programlisting>
|
|
438 CREATE name2,02,03
|
|
439 CREATE name3,01,02
|
|
440 </programlisting>
|
|
441 <para>
|
|
442 The above macro calls will produce the following in-line code:
|
|
443 </para>
|
|
444 <programlisting>
|
|
445 leax name2, pcr
|
|
446 lda $02
|
|
447 ldb $03
|
|
448 os9 I$CREATE
|
|
449
|
|
450 leax name3, pcr
|
|
451 lda $01
|
|
452 ldb $02
|
|
453 os9 I$CREATE
|
|
454 </programlisting>
|
|
455 <para>
|
|
456 If an argument has multiple parts, for example if d1,d2 is to be
|
|
457 passed to the macro called frud, it must be passed in double quotes.
|
|
458 For example:
|
|
459 </para>
|
|
460 <programlisting>
|
|
461 frud "0,s","2,s"
|
|
462 </programlisting>
|
|
463 <para>
|
|
464 If frud looks like the following macro:
|
|
465 <programlisting>
|
|
466 frud MACRO
|
|
467 \@ leau \1
|
|
468 ldd \2
|
|
469 beq \@
|
|
470 ENDM
|
|
471 </programlisting>
|
|
472 The previous call to frud would expand the macro as follows:
|
|
473 <programlisting>
|
|
474 @xxx leau 0,s
|
|
475 ldd 2,s
|
|
476 beq @xxx
|
|
477 </programlisting>
|
|
478 Where "\@" is a label, and "xxx" would be replaced
|
|
479 by a three digit number.
|
|
480 </para>
|
|
481 <para>
|
|
482 An argument may be declared null by leaving it blank in the macro
|
|
483 call. For example, if the macro instruction was "ldd \1ZZ\2", then
|
|
484 the call to the macro with arguments AA,BB would expand the
|
|
485 instruction to "ldd AAZZBB", and the call with argument ,BB will
|
|
486 expand it to "ldd ZZBB".
|
530
|
487 </para>
|
|
488 </section>
|
|
489
|
|
490 <section>
|
|
491 <title>Nested Macro Calls</title>
|
|
492 <para>
|
653
|
493 Macro calls may be nested, that is, the body of a macro definition
|
|
494 may contain a call to another macro. For example, the macro prepw
|
|
495 could be defined as follows:
|
|
496 <programlisting>
|
|
497 prepw MACRO
|
|
498 lda \1
|
|
499 getw
|
|
500 ENDM
|
|
501 </programlisting>
|
|
502 Getw is a macro call. The code to getw is substituted in-line at
|
|
503 expansion time. However, the definition of a new macro within
|
|
504 another is not permitted. Macro calls may be nested up to eight deep.
|
530
|
505 </para>
|
|
506 </section>
|
|
507
|
|
508 <section>
|
|
509 <title>Labels</title>
|
|
510 <para>
|
552
|
511 Sometimes it is necessary to use labels within a macro. Labels are
|
|
512 specified by <quote>\@</quote>. Each time the macro is called, a unique label
|
|
513 will be generated to avoid multiple definition errors. Within the
|
|
514 expanded code <quote>\@</quote> will take on the form <quote>@xxx</quote>, where xxx
|
|
515 will be a decimal number between 000 to 999.
|
|
516 </para>
|
|
517 <para>
|
653
|
518 More than one label may be specified in a macro by the addition of
|
|
519 an extra character(s). For example, if two different labels are
|
|
520 required in a macro, they can be specified by "\@A" and "\@B". In
|
|
521 the first expansion of te macro, the labels would be "@001A" and
|
|
522 "@001B", and in the second expansion they would be "@002A" and
|
|
523 "@002B". The extra characters may be appended before the "\" or
|
|
524 after the "@".
|
530
|
525 </para>
|
|
526 </section>
|
|
527
|
|
528 <section>
|
|
529 <title>Additional Pseudo-Instructions</title>
|
563
|
530 <variablelist>
|
|
531 <varlistentry><term>\n</term>
|
|
532 <listitem>
|
530
|
533 <para>
|
563
|
534 will return the number of arguments passed to the macro.
|
530
|
535 </para>
|
563
|
536 </listitem>
|
|
537 </varlistentry>
|
|
538
|
|
539 <varlistentry><term>\L<num></term>
|
|
540 <listitem>
|
|
541 <para>
|
|
542 will return the length of the ith argument
|
|
543 that is specified by <num>.
|
|
544 </para>
|
|
545 </listitem>
|
|
546 </varlistentry>
|
|
547
|
|
548 <varlistentry><term>FAIL</term>
|
|
549 <listitem>
|
|
550 <para>
|
|
551 Causes an error to be generated.
|
|
552 </para>
|
|
553 </listitem>
|
|
554 </varlistentry>
|
|
555
|
|
556 <varlistentry><term>REPT <num></term>
|
|
557 <listitem>
|
|
558 <para>
|
|
559 will repeat an instruction or group of instructions <num> times.
|
|
560 ENDR terminates REPT.
|
|
561 </para>
|
|
562 </listitem>
|
|
563 </varlistentry>
|
|
564
|
|
565 </variablelist>
|
530
|
566 </section>
|
|
567 </section>
|
466
|
568 </appendix>
|