189 lines
10 KiB
HTML
189 lines
10 KiB
HTML
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Macro - Using as</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="Using as">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="up" href="Pseudo-Ops.html#Pseudo-Ops" title="Pseudo Ops">
|
||
|
|
<link rel="prev" href="Long.html#Long" title="Long">
|
||
|
|
<link rel="next" href="MRI.html#MRI" title="MRI">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
This file documents the GNU Assembler "as".
|
||
|
|
|
||
|
|
Copyright (C) 1991-2019 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3
|
||
|
|
or any later version published by the Free Software Foundation;
|
||
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
||
|
|
Back-Cover Texts. A copy of the license is included in the
|
||
|
|
section entitled ``GNU Free Documentation License''.
|
||
|
|
|
||
|
|
-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Macro"></a>
|
||
|
|
<p>
|
||
|
|
Next: <a rel="next" accesskey="n" href="MRI.html#MRI">MRI</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="Long.html#Long">Long</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="Pseudo-Ops.html#Pseudo-Ops">Pseudo Ops</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">7.61 <code>.macro</code></h3>
|
||
|
|
|
||
|
|
<p><a name="index-macros-405"></a>The commands <code>.macro</code> and <code>.endm</code> allow you to define macros that
|
||
|
|
generate assembly output. For example, this definition specifies a macro
|
||
|
|
<code>sum</code> that puts a sequence of numbers into memory:
|
||
|
|
|
||
|
|
<pre class="example"> .macro sum from=0, to=5
|
||
|
|
.long \from
|
||
|
|
.if \to-\from
|
||
|
|
sum "(\from+1)",\to
|
||
|
|
.endif
|
||
|
|
.endm
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">With that definition, ‘<samp><span class="samp">SUM 0,5</span></samp>’ is equivalent to this assembly input:
|
||
|
|
|
||
|
|
<pre class="example"> .long 0
|
||
|
|
.long 1
|
||
|
|
.long 2
|
||
|
|
.long 3
|
||
|
|
.long 4
|
||
|
|
.long 5
|
||
|
|
</pre>
|
||
|
|
<dl>
|
||
|
|
<dt><code>.macro </code><var>macname</var><a name="index-g_t_002emacro-_0040var_007bmacname_007d-406"></a><dt><code>.macro </code><var>macname</var> <var>macargs</var><code> ...</code><a name="index-g_t_002emacro-_0040var_007bmacname_007d-_0040var_007bmacargs_007d-_0040dots_007b_007d-407"></a><dd><a name="index-g_t_0040code_007bmacro_007d-directive-408"></a>Begin the definition of a macro called <var>macname</var>. If your macro
|
||
|
|
definition requires arguments, specify their names after the macro name,
|
||
|
|
separated by commas or spaces. You can qualify the macro argument to
|
||
|
|
indicate whether all invocations must specify a non-blank value (through
|
||
|
|
‘<samp><span class="samp">:</span><code>req</code></samp>’), or whether it takes all of the remaining arguments
|
||
|
|
(through ‘<samp><span class="samp">:</span><code>vararg</code></samp>’). You can supply a default value for any
|
||
|
|
macro argument by following the name with ‘<samp><span class="samp">=</span><var>deflt</var></samp>’. You
|
||
|
|
cannot define two macros with the same <var>macname</var> unless it has been
|
||
|
|
subject to the <code>.purgem</code> directive (see <a href="Purgem.html#Purgem">Purgem</a>) between the two
|
||
|
|
definitions. For example, these are all valid <code>.macro</code> statements:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>.macro comm</code><dd>Begin the definition of a macro called <code>comm</code>, which takes no
|
||
|
|
arguments.
|
||
|
|
|
||
|
|
<br><dt><code>.macro plus1 p, p1</code><dt><code>.macro plus1 p p1</code><dd>Either statement begins the definition of a macro called <code>plus1</code>,
|
||
|
|
which takes two arguments; within the macro definition, write
|
||
|
|
‘<samp><span class="samp">\p</span></samp>’ or ‘<samp><span class="samp">\p1</span></samp>’ to evaluate the arguments.
|
||
|
|
|
||
|
|
<br><dt><code>.macro reserve_str p1=0 p2</code><dd>Begin the definition of a macro called <code>reserve_str</code>, with two
|
||
|
|
arguments. The first argument has a default value, but not the second.
|
||
|
|
After the definition is complete, you can call the macro either as
|
||
|
|
‘<samp><span class="samp">reserve_str </span><var>a</var><span class="samp">,</span><var>b</var></samp>’ (with ‘<samp><span class="samp">\p1</span></samp>’ evaluating to
|
||
|
|
<var>a</var> and ‘<samp><span class="samp">\p2</span></samp>’ evaluating to <var>b</var>), or as ‘<samp><span class="samp">reserve_str
|
||
|
|
,</span><var>b</var></samp>’ (with ‘<samp><span class="samp">\p1</span></samp>’ evaluating as the default, in this case
|
||
|
|
‘<samp><span class="samp">0</span></samp>’, and ‘<samp><span class="samp">\p2</span></samp>’ evaluating to <var>b</var>).
|
||
|
|
|
||
|
|
<br><dt><code>.macro m p1:req, p2=0, p3:vararg</code><dd>Begin the definition of a macro called <code>m</code>, with at least three
|
||
|
|
arguments. The first argument must always have a value specified, but
|
||
|
|
not the second, which instead has a default value. The third formal
|
||
|
|
will get assigned all remaining arguments specified at invocation time.
|
||
|
|
|
||
|
|
<p>When you call a macro, you can specify the argument values either by
|
||
|
|
position, or by keyword. For example, ‘<samp><span class="samp">sum 9,17</span></samp>’ is equivalent to
|
||
|
|
‘<samp><span class="samp">sum to=17, from=9</span></samp>’.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Note that since each of the <var>macargs</var> can be an identifier exactly
|
||
|
|
as any other one permitted by the target architecture, there may be
|
||
|
|
occasional problems if the target hand-crafts special meanings to certain
|
||
|
|
characters when they occur in a special position. For example, if the colon
|
||
|
|
(<code>:</code>) is generally permitted to be part of a symbol name, but the
|
||
|
|
architecture specific code special-cases it when occurring as the final
|
||
|
|
character of a symbol (to denote a label), then the macro parameter
|
||
|
|
replacement code will have no way of knowing that and consider the whole
|
||
|
|
construct (including the colon) an identifier, and check only this
|
||
|
|
identifier for being the subject to parameter substitution. So for example
|
||
|
|
this macro definition:
|
||
|
|
|
||
|
|
<pre class="example"> .macro label l
|
||
|
|
\l:
|
||
|
|
.endm
|
||
|
|
</pre>
|
||
|
|
<p>might not work as expected. Invoking ‘<samp><span class="samp">label foo</span></samp>’ might not create a label
|
||
|
|
called ‘<samp><span class="samp">foo</span></samp>’ but instead just insert the text ‘<samp><span class="samp">\l:</span></samp>’ into the
|
||
|
|
assembler source, probably generating an error about an unrecognised
|
||
|
|
identifier.
|
||
|
|
|
||
|
|
<p>Similarly problems might occur with the period character (‘<samp><span class="samp">.</span></samp>’)
|
||
|
|
which is often allowed inside opcode names (and hence identifier names). So
|
||
|
|
for example constructing a macro to build an opcode from a base name and a
|
||
|
|
length specifier like this:
|
||
|
|
|
||
|
|
<pre class="example"> .macro opcode base length
|
||
|
|
\base.\length
|
||
|
|
.endm
|
||
|
|
</pre>
|
||
|
|
<p>and invoking it as ‘<samp><span class="samp">opcode store l</span></samp>’ will not create a ‘<samp><span class="samp">store.l</span></samp>’
|
||
|
|
instruction but instead generate some kind of error as the assembler tries to
|
||
|
|
interpret the text ‘<samp><span class="samp">\base.\length</span></samp>’.
|
||
|
|
|
||
|
|
<p>There are several possible ways around this problem:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>Insert white space</code><dd>If it is possible to use white space characters then this is the simplest
|
||
|
|
solution. eg:
|
||
|
|
|
||
|
|
<pre class="example"> .macro label l
|
||
|
|
\l :
|
||
|
|
.endm
|
||
|
|
</pre>
|
||
|
|
<br><dt><code>Use ‘</code><samp><span class="samp">\()</span></samp><code>’</code><dd>The string ‘<samp><span class="samp">\()</span></samp>’ can be used to separate the end of a macro argument from
|
||
|
|
the following text. eg:
|
||
|
|
|
||
|
|
<pre class="example"> .macro opcode base length
|
||
|
|
\base\().\length
|
||
|
|
.endm
|
||
|
|
</pre>
|
||
|
|
<br><dt><code>Use the alternate macro syntax mode</code><dd>In the alternative macro syntax mode the ampersand character (‘<samp><span class="samp">&</span></samp>’) can be
|
||
|
|
used as a separator. eg:
|
||
|
|
|
||
|
|
<pre class="example"> .altmacro
|
||
|
|
.macro label l
|
||
|
|
l&:
|
||
|
|
.endm
|
||
|
|
</pre>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Note: this problem of correctly identifying string parameters to pseudo ops
|
||
|
|
also applies to the identifiers used in <code>.irp</code> (see <a href="Irp.html#Irp">Irp</a>)
|
||
|
|
and <code>.irpc</code> (see <a href="Irpc.html#Irpc">Irpc</a>) as well.
|
||
|
|
|
||
|
|
<br><dt><code>.endm</code><a name="index-g_t_002eendm-409"></a><dd><a name="index-g_t_0040code_007bendm_007d-directive-410"></a>Mark the end of a macro definition.
|
||
|
|
|
||
|
|
<br><dt><code>.exitm</code><a name="index-g_t_002eexitm-411"></a><dd><a name="index-g_t_0040code_007bexitm_007d-directive-412"></a>Exit early from the current macro definition.
|
||
|
|
|
||
|
|
<p><a name="index-number-of-macros-executed-413"></a><a name="index-macros_002c-count-executed-414"></a><br><dt><code>\@</code><a name="index-g_t_005c_0040_0040-415"></a><dd><samp><span class="command">as</span></samp> maintains a counter of how many macros it has
|
||
|
|
executed in this pseudo-variable; you can copy that number to your
|
||
|
|
output with ‘<samp><span class="samp">\@</span></samp>’, but <em>only within a macro definition</em>.
|
||
|
|
|
||
|
|
<br><dt><code>LOCAL </code><var>name</var><code> [ , ... ]</code><a name="index-LOCAL-_0040var_007bname_007d-_005b-_002c-_0040dots_007b_007d-_005d-416"></a><dd><em>Warning: </em><code>LOCAL</code><em> is only available if you select “alternate
|
||
|
|
macro syntax” with ‘</em><samp><span class="samp">--alternate</span></samp><em>’ or </em><code>.altmacro</code><em>.</em>
|
||
|
|
See <a href="Altmacro.html#Altmacro"><code>.altmacro</code></a>.
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|