1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- This file documents the GNU Assembler "as". 4 5Copyright (C) 1991-2021 Free Software Foundation, Inc. 6 7Permission is granted to copy, distribute and/or modify this document 8under the terms of the GNU Free Documentation License, Version 1.3 9or any later version published by the Free Software Foundation; 10with no Invariant Sections, with no Front-Cover Texts, and with no 11Back-Cover Texts. A copy of the license is included in the 12section entitled "GNU Free Documentation License". 13 --> 14<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 15<head> 16<title>Using as: Macro</title> 17 18<meta name="description" content="Using as: Macro"> 19<meta name="keywords" content="Using as: Macro"> 20<meta name="resource-type" content="document"> 21<meta name="distribution" content="global"> 22<meta name="Generator" content="makeinfo"> 23<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 24<link href="index.html#Top" rel="start" title="Top"> 25<link href="AS-Index.html#AS-Index" rel="index" title="AS Index"> 26<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 27<link href="Pseudo-Ops.html#Pseudo-Ops" rel="up" title="Pseudo Ops"> 28<link href="MRI.html#MRI" rel="next" title="MRI"> 29<link href="Long.html#Long" rel="previous" title="Long"> 30<style type="text/css"> 31<!-- 32a.summary-letter {text-decoration: none} 33blockquote.smallquotation {font-size: smaller} 34div.display {margin-left: 3.2em} 35div.example {margin-left: 3.2em} 36div.indentedblock {margin-left: 3.2em} 37div.lisp {margin-left: 3.2em} 38div.smalldisplay {margin-left: 3.2em} 39div.smallexample {margin-left: 3.2em} 40div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 41div.smalllisp {margin-left: 3.2em} 42kbd {font-style:oblique} 43pre.display {font-family: inherit} 44pre.format {font-family: inherit} 45pre.menu-comment {font-family: serif} 46pre.menu-preformatted {font-family: serif} 47pre.smalldisplay {font-family: inherit; font-size: smaller} 48pre.smallexample {font-size: smaller} 49pre.smallformat {font-family: inherit; font-size: smaller} 50pre.smalllisp {font-size: smaller} 51span.nocodebreak {white-space:nowrap} 52span.nolinebreak {white-space:nowrap} 53span.roman {font-family:serif; font-weight:normal} 54span.sansserif {font-family:sans-serif; font-weight:normal} 55ul.no-bullet {list-style: none} 56--> 57</style> 58 59 60</head> 61 62<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 63<a name="Macro"></a> 64<div class="header"> 65<p> 66Next: <a href="MRI.html#MRI" accesskey="n" rel="next">MRI</a>, Previous: <a href="Long.html#Long" accesskey="p" rel="previous">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> 67</div> 68<hr> 69<a name="g_t_002emacro"></a> 70<h3 class="section">7.62 <code>.macro</code></h3> 71 72<a name="index-macros"></a> 73<p>The commands <code>.macro</code> and <code>.endm</code> allow you to define macros that 74generate assembly output. For example, this definition specifies a macro 75<code>sum</code> that puts a sequence of numbers into memory: 76</p> 77<div class="example"> 78<pre class="example"> .macro sum from=0, to=5 79 .long \from 80 .if \to-\from 81 sum "(\from+1)",\to 82 .endif 83 .endm 84</pre></div> 85 86<p>With that definition, ‘<samp>SUM 0,5</samp>’ is equivalent to this assembly input: 87</p> 88<div class="example"> 89<pre class="example"> .long 0 90 .long 1 91 .long 2 92 .long 3 93 .long 4 94 .long 5 95</pre></div> 96 97<dl compact="compact"> 98<dt><code>.macro <var>macname</var></code> 99<a name="index-_002emacro-macname"></a> 100</dt> 101<dt><code>.macro <var>macname</var> <var>macargs</var> …</code> 102<a name="index-_002emacro-macname-macargs-_2026"></a> 103</dt> 104<dd><a name="index-macro-directive"></a> 105<p>Begin the definition of a macro called <var>macname</var>. If your macro 106definition requires arguments, specify their names after the macro name, 107separated by commas or spaces. You can qualify the macro argument to 108indicate whether all invocations must specify a non-blank value (through 109‘<samp>:<code>req</code></samp>’), or whether it takes all of the remaining arguments 110(through ‘<samp>:<code>vararg</code></samp>’). You can supply a default value for any 111macro argument by following the name with ‘<samp>=<var>deflt</var></samp>’. You 112cannot define two macros with the same <var>macname</var> unless it has been 113subject to the <code>.purgem</code> directive (see <a href="Purgem.html#Purgem">Purgem</a>) between the two 114definitions. For example, these are all valid <code>.macro</code> statements: 115</p> 116<dl compact="compact"> 117<dt><code>.macro comm</code></dt> 118<dd><p>Begin the definition of a macro called <code>comm</code>, which takes no 119arguments. 120</p> 121</dd> 122<dt><code>.macro plus1 p, p1</code></dt> 123<dt><code>.macro plus1 p p1</code></dt> 124<dd><p>Either statement begins the definition of a macro called <code>plus1</code>, 125which takes two arguments; within the macro definition, write 126‘<samp>\p</samp>’ or ‘<samp>\p1</samp>’ to evaluate the arguments. 127</p> 128</dd> 129<dt><code>.macro reserve_str p1=0 p2</code></dt> 130<dd><p>Begin the definition of a macro called <code>reserve_str</code>, with two 131arguments. The first argument has a default value, but not the second. 132After the definition is complete, you can call the macro either as 133‘<samp>reserve_str <var>a</var>,<var>b</var></samp>’ (with ‘<samp>\p1</samp>’ evaluating to 134<var>a</var> and ‘<samp>\p2</samp>’ evaluating to <var>b</var>), or as ‘<samp>reserve_str 135,<var>b</var></samp>’ (with ‘<samp>\p1</samp>’ evaluating as the default, in this case 136‘<samp>0</samp>’, and ‘<samp>\p2</samp>’ evaluating to <var>b</var>). 137</p> 138</dd> 139<dt><code>.macro m p1:req, p2=0, p3:vararg</code></dt> 140<dd><p>Begin the definition of a macro called <code>m</code>, with at least three 141arguments. The first argument must always have a value specified, but 142not the second, which instead has a default value. The third formal 143will get assigned all remaining arguments specified at invocation time. 144</p> 145<p>When you call a macro, you can specify the argument values either by 146position, or by keyword. For example, ‘<samp>sum 9,17</samp>’ is equivalent to 147‘<samp>sum to=17, from=9</samp>’. 148</p> 149</dd> 150</dl> 151 152<p>Note that since each of the <var>macargs</var> can be an identifier exactly 153as any other one permitted by the target architecture, there may be 154occasional problems if the target hand-crafts special meanings to certain 155characters when they occur in a special position. For example, if the colon 156(<code>:</code>) is generally permitted to be part of a symbol name, but the 157architecture specific code special-cases it when occurring as the final 158character of a symbol (to denote a label), then the macro parameter 159replacement code will have no way of knowing that and consider the whole 160construct (including the colon) an identifier, and check only this 161identifier for being the subject to parameter substitution. So for example 162this macro definition: 163</p> 164<div class="example"> 165<pre class="example"> .macro label l 166\l: 167 .endm 168</pre></div> 169 170<p>might not work as expected. Invoking ‘<samp>label foo</samp>’ might not create a label 171called ‘<samp>foo</samp>’ but instead just insert the text ‘<samp>\l:</samp>’ into the 172assembler source, probably generating an error about an unrecognised 173identifier. 174</p> 175<p>Similarly problems might occur with the period character (‘<samp>.</samp>’) 176which is often allowed inside opcode names (and hence identifier names). So 177for example constructing a macro to build an opcode from a base name and a 178length specifier like this: 179</p> 180<div class="example"> 181<pre class="example"> .macro opcode base length 182 \base.\length 183 .endm 184</pre></div> 185 186<p>and invoking it as ‘<samp>opcode store l</samp>’ will not create a ‘<samp>store.l</samp>’ 187instruction but instead generate some kind of error as the assembler tries to 188interpret the text ‘<samp>\base.\length</samp>’. 189</p> 190<p>There are several possible ways around this problem: 191</p> 192<dl compact="compact"> 193<dt><code>Insert white space</code></dt> 194<dd><p>If it is possible to use white space characters then this is the simplest 195solution. eg: 196</p> 197<div class="example"> 198<pre class="example"> .macro label l 199\l : 200 .endm 201</pre></div> 202 203</dd> 204<dt><code>Use ‘<samp>\()</samp>’</code></dt> 205<dd><p>The string ‘<samp>\()</samp>’ can be used to separate the end of a macro argument from 206the following text. eg: 207</p> 208<div class="example"> 209<pre class="example"> .macro opcode base length 210 \base\().\length 211 .endm 212</pre></div> 213 214</dd> 215<dt><code>Use the alternate macro syntax mode</code></dt> 216<dd><p>In the alternative macro syntax mode the ampersand character (‘<samp>&</samp>’) can be 217used as a separator. eg: 218</p> 219<div class="example"> 220<pre class="example"> .altmacro 221 .macro label l 222l&: 223 .endm 224</pre></div> 225</dd> 226</dl> 227 228<p>Note: this problem of correctly identifying string parameters to pseudo ops 229also applies to the identifiers used in <code>.irp</code> (see <a href="Irp.html#Irp">Irp</a>) 230and <code>.irpc</code> (see <a href="Irpc.html#Irpc">Irpc</a>) as well. 231</p> 232</dd> 233<dt><code>.endm</code> 234<a name="index-_002eendm"></a> 235</dt> 236<dd><a name="index-endm-directive"></a> 237<p>Mark the end of a macro definition. 238</p> 239</dd> 240<dt><code>.exitm</code> 241<a name="index-_002eexitm"></a> 242</dt> 243<dd><a name="index-exitm-directive"></a> 244<p>Exit early from the current macro definition. 245</p> 246<a name="index-number-of-macros-executed"></a> 247<a name="index-macros_002c-count-executed"></a> 248</dd> 249<dt><code>\@</code> 250<a name="index-_005c_0040"></a> 251</dt> 252<dd><p><code>as</code> maintains a counter of how many macros it has 253executed in this pseudo-variable; you can copy that number to your 254output with ‘<samp>\@</samp>’, but <em>only within a macro definition</em>. 255</p> 256</dd> 257<dt><code>LOCAL <var>name</var> [ , … ]</code> 258<a name="index-LOCAL-name-_005b-_002c-_2026-_005d-1"></a> 259</dt> 260<dd><p><em>Warning: <code>LOCAL</code> is only available if you select “alternate 261macro syntax” with ‘<samp>--alternate</samp>’ or <code>.altmacro</code>.</em> 262See <a href="Altmacro.html#Altmacro"><code>.altmacro</code></a>. 263</p></dd> 264</dl> 265 266<hr> 267<div class="header"> 268<p> 269Next: <a href="MRI.html#MRI" accesskey="n" rel="next">MRI</a>, Previous: <a href="Long.html#Long" accesskey="p" rel="previous">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> 270</div> 271 272 273 274</body> 275</html> 276