276 lines
11 KiB
HTML
276 lines
11 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- This file documents the GNU Assembler "as".
|
||
|
|
|
||
|
|
Copyright (C) 1991-2016 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".
|
||
|
|
-->
|
||
|
|
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Using as: Macro</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Using as: Macro">
|
||
|
|
<meta name="keywords" content="Using as: Macro">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="AS-Index.html#AS-Index" rel="index" title="AS Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Pseudo-Ops.html#Pseudo-Ops" rel="up" title="Pseudo Ops">
|
||
|
|
<link href="MRI.html#MRI" rel="next" title="MRI">
|
||
|
|
<link href="Long.html#Long" rel="prev" title="Long">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.indentedblock {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style:oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nocodebreak {white-space:nowrap}
|
||
|
|
span.nolinebreak {white-space:nowrap}
|
||
|
|
span.roman {font-family:serif; font-weight:normal}
|
||
|
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
||
|
|
<a name="Macro"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="MRI.html#MRI" accesskey="n" rel="next">MRI</a>, Previous: <a href="Long.html#Long" accesskey="p" rel="prev">Long</a>, Up: <a href="Pseudo-Ops.html#Pseudo-Ops" accesskey="u" rel="up">Pseudo Ops</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="g_t_002emacro"></a>
|
||
|
|
<h3 class="section">7.58 <code>.macro</code></h3>
|
||
|
|
|
||
|
|
<a name="index-macros"></a>
|
||
|
|
<p>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:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .macro sum from=0, to=5
|
||
|
|
.long \from
|
||
|
|
.if \to-\from
|
||
|
|
sum "(\from+1)",\to
|
||
|
|
.endif
|
||
|
|
.endm
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>With that definition, ‘<samp>SUM 0,5</samp>’ is equivalent to this assembly input:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .long 0
|
||
|
|
.long 1
|
||
|
|
.long 2
|
||
|
|
.long 3
|
||
|
|
.long 4
|
||
|
|
.long 5
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>.macro <var>macname</var></code>
|
||
|
|
<a name="index-_002emacro-macname"></a>
|
||
|
|
</dt>
|
||
|
|
<dt><code>.macro <var>macname</var> <var>macargs</var> …</code>
|
||
|
|
<a name="index-_002emacro-macname-macargs-_2026"></a>
|
||
|
|
</dt>
|
||
|
|
<dd><a name="index-macro-directive"></a>
|
||
|
|
<p>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>:<code>req</code></samp>’), or whether it takes all of the remaining arguments
|
||
|
|
(through ‘<samp>:<code>vararg</code></samp>’). You can supply a default value for any
|
||
|
|
macro argument by following the name with ‘<samp>=<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:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>.macro comm</code></dt>
|
||
|
|
<dd><p>Begin the definition of a macro called <code>comm</code>, which takes no
|
||
|
|
arguments.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>.macro plus1 p, p1</code></dt>
|
||
|
|
<dt><code>.macro plus1 p p1</code></dt>
|
||
|
|
<dd><p>Either statement begins the definition of a macro called <code>plus1</code>,
|
||
|
|
which takes two arguments; within the macro definition, write
|
||
|
|
‘<samp>\p</samp>’ or ‘<samp>\p1</samp>’ to evaluate the arguments.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>.macro reserve_str p1=0 p2</code></dt>
|
||
|
|
<dd><p>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>reserve_str <var>a</var>,<var>b</var></samp>’ (with ‘<samp>\p1</samp>’ evaluating to
|
||
|
|
<var>a</var> and ‘<samp>\p2</samp>’ evaluating to <var>b</var>), or as ‘<samp>reserve_str
|
||
|
|
,<var>b</var></samp>’ (with ‘<samp>\p1</samp>’ evaluating as the default, in this case
|
||
|
|
‘<samp>0</samp>’, and ‘<samp>\p2</samp>’ evaluating to <var>b</var>).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>.macro m p1:req, p2=0, p3:vararg</code></dt>
|
||
|
|
<dd><p>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>
|
||
|
|
<p>When you call a macro, you can specify the argument values either by
|
||
|
|
position, or by keyword. For example, ‘<samp>sum 9,17</samp>’ is equivalent to
|
||
|
|
‘<samp>sum to=17, from=9</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</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:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .macro label l
|
||
|
|
\l:
|
||
|
|
.endm
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>might not work as expected. Invoking ‘<samp>label foo</samp>’ might not create a label
|
||
|
|
called ‘<samp>foo</samp>’ but instead just insert the text ‘<samp>\l:</samp>’ into the
|
||
|
|
assembler source, probably generating an error about an unrecognised
|
||
|
|
identifier.
|
||
|
|
</p>
|
||
|
|
<p>Similarly problems might occur with the period character (‘<samp>.</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:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .macro opcode base length
|
||
|
|
\base.\length
|
||
|
|
.endm
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>and invoking it as ‘<samp>opcode store l</samp>’ will not create a ‘<samp>store.l</samp>’
|
||
|
|
instruction but instead generate some kind of error as the assembler tries to
|
||
|
|
interpret the text ‘<samp>\base.\length</samp>’.
|
||
|
|
</p>
|
||
|
|
<p>There are several possible ways around this problem:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>Insert white space</code></dt>
|
||
|
|
<dd><p>If it is possible to use white space characters then this is the simplest
|
||
|
|
solution. eg:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .macro label l
|
||
|
|
\l :
|
||
|
|
.endm
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>Use ‘<samp>\()</samp>’</code></dt>
|
||
|
|
<dd><p>The string ‘<samp>\()</samp>’ can be used to separate the end of a macro argument from
|
||
|
|
the following text. eg:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .macro opcode base length
|
||
|
|
\base\().\length
|
||
|
|
.endm
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><code>Use the alternate macro syntax mode</code></dt>
|
||
|
|
<dd><p>In the alternative macro syntax mode the ampersand character (‘<samp>&</samp>’) can be
|
||
|
|
used as a separator. eg:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example"> .altmacro
|
||
|
|
.macro label l
|
||
|
|
l&:
|
||
|
|
.endm
|
||
|
|
</pre></div>
|
||
|
|
</dd>
|
||
|
|
</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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>.endm</code>
|
||
|
|
<a name="index-_002eendm"></a>
|
||
|
|
</dt>
|
||
|
|
<dd><a name="index-endm-directive"></a>
|
||
|
|
<p>Mark the end of a macro definition.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>.exitm</code>
|
||
|
|
<a name="index-_002eexitm"></a>
|
||
|
|
</dt>
|
||
|
|
<dd><a name="index-exitm-directive"></a>
|
||
|
|
<p>Exit early from the current macro definition.
|
||
|
|
</p>
|
||
|
|
<a name="index-number-of-macros-executed"></a>
|
||
|
|
<a name="index-macros_002c-count-executed"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>\@</code>
|
||
|
|
<a name="index-_005c_0040"></a>
|
||
|
|
</dt>
|
||
|
|
<dd><p><code>as</code> maintains a counter of how many macros it has
|
||
|
|
executed in this pseudo-variable; you can copy that number to your
|
||
|
|
output with ‘<samp>\@</samp>’, but <em>only within a macro definition</em>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>LOCAL <var>name</var> [ , … ]</code>
|
||
|
|
<a name="index-LOCAL-name-_005b-_002c-_2026-_005d-1"></a>
|
||
|
|
</dt>
|
||
|
|
<dd><p><em>Warning: <code>LOCAL</code> is only available if you select “alternate
|
||
|
|
macro syntax” with ‘<samp>--alternate</samp>’ or <code>.altmacro</code>.</em>
|
||
|
|
See <a href="Altmacro.html#Altmacro"><code>.altmacro</code></a>.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="MRI.html#MRI" accesskey="n" rel="next">MRI</a>, Previous: <a href="Long.html#Long" accesskey="p" rel="prev">Long</a>, Up: <a href="Pseudo-Ops.html#Pseudo-Ops" accesskey="u" rel="up">Pseudo Ops</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="AS-Index.html#AS-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|