| <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: <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.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, ‘<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-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 |
| ‘<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-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 ‘<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-401"></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> |
| |
