<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, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2006, 2007, 2008, 2009, 2010 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>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Macro"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="MRI.html#MRI">MRI</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Long.html#Long">Long</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Pseudo-Ops.html#Pseudo-Ops">Pseudo Ops</a>
<hr>
</div>

<h3 class="section">7.77 <code>.macro</code></h3>

<p><a name="index-macros-390"></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, &lsquo;<samp><span class="samp">SUM 0,5</span></samp>&rsquo; 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-391"></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-392"></a><dd><a name="index-g_t_0040code_007bmacro_007d-directive-393"></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
&lsquo;<samp><span class="samp">:</span><code>req</code></samp>&rsquo;), or whether it takes all of the remaining arguments
(through &lsquo;<samp><span class="samp">:</span><code>vararg</code></samp>&rsquo;).  You can supply a default value for any
macro argument by following the name with &lsquo;<samp><span class="samp">=</span><var>deflt</var></samp>&rsquo;.  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
&lsquo;<samp><span class="samp">\p</span></samp>&rsquo; or &lsquo;<samp><span class="samp">\p1</span></samp>&rsquo; 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
&lsquo;<samp><span class="samp">reserve_str </span><var>a</var><span class="samp">,</span><var>b</var></samp>&rsquo; (with &lsquo;<samp><span class="samp">\p1</span></samp>&rsquo; evaluating to
<var>a</var> and &lsquo;<samp><span class="samp">\p2</span></samp>&rsquo; evaluating to <var>b</var>), or as &lsquo;<samp><span class="samp">reserve_str
,</span><var>b</var></samp>&rsquo; (with &lsquo;<samp><span class="samp">\p1</span></samp>&rsquo; evaluating as the default, in this case
&lsquo;<samp><span class="samp">0</span></samp>&rsquo;, and &lsquo;<samp><span class="samp">\p2</span></samp>&rsquo; 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, &lsquo;<samp><span class="samp">sum 9,17</span></samp>&rsquo; is equivalent to
&lsquo;<samp><span class="samp">sum to=17, from=9</span></samp>&rsquo;.

     </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 &lsquo;<samp><span class="samp">label foo</span></samp>&rsquo; might not create a label
called &lsquo;<samp><span class="samp">foo</span></samp>&rsquo; but instead just insert the text &lsquo;<samp><span class="samp">\l:</span></samp>&rsquo; into the
assembler source, probably generating an error about an unrecognised
identifier.

     <p>Similarly problems might occur with the period character (&lsquo;<samp><span class="samp">.</span></samp>&rsquo;)
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 &lsquo;<samp><span class="samp">opcode store l</span></samp>&rsquo; will not create a &lsquo;<samp><span class="samp">store.l</span></samp>&rsquo;
instruction but instead generate some kind of error as the assembler tries to
interpret the text &lsquo;<samp><span class="samp">\base.\length</span></samp>&rsquo;.

     <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 &lsquo;</code><samp><span class="samp">\()</span></samp><code>&rsquo;</code><dd>The string &lsquo;<samp><span class="samp">\()</span></samp>&rsquo; 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 (&lsquo;<samp><span class="samp">&amp;</span></samp>&rsquo;) can be
used as a separator.  eg:

          <pre class="example">               	.altmacro
               	.macro label l
               l&amp;:
               	.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-394"></a><dd><a name="index-g_t_0040code_007bendm_007d-directive-395"></a>Mark the end of a macro definition.

     <br><dt><code>.exitm</code><a name="index-g_t_002eexitm-396"></a><dd><a name="index-g_t_0040code_007bexitm_007d-directive-397"></a>Exit early from the current macro definition.

     <p><a name="index-number-of-macros-executed-398"></a><a name="index-macros_002c-count-executed-399"></a><br><dt><code>\@</code><a name="index-g_t_005c_0040_0040-400"></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 &lsquo;<samp><span class="samp">\@</span></samp>&rsquo;, 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-401"></a><dd><em>Warning: </em><code>LOCAL</code><em> is only available if you select &ldquo;alternate
macro syntax&rdquo; with &lsquo;</em><samp><span class="samp">--alternate</span></samp><em>&rsquo; or </em><code>.altmacro</code><em>.</em>
See <a href="Altmacro.html#Altmacro"><code>.altmacro</code></a>. 
</dl>

   </body></html>