as: Macro
1
1 7.59 '.macro'
1 =============
1
1 The commands '.macro' and '.endm' allow you to define macros that
1 generate assembly output. For example, this definition specifies a
1 macro 'sum' that puts a sequence of numbers into memory:
1
1 .macro sum from=0, to=5
1 .long \from
1 .if \to-\from
1 sum "(\from+1)",\to
1 .endif
1 .endm
1
1 With that definition, 'SUM 0,5' is equivalent to this assembly input:
1
1 .long 0
1 .long 1
1 .long 2
1 .long 3
1 .long 4
1 .long 5
1
1 '.macro MACNAME'
1 '.macro MACNAME MACARGS ...'
1 Begin the definition of a macro called MACNAME. If your macro
1 definition requires arguments, specify their names after the macro
1 name, separated by commas or spaces. You can qualify the macro
1 argument to indicate whether all invocations must specify a
1 non-blank value (through ':'req''), or whether it takes all of the
1 remaining arguments (through ':'vararg''). You can supply a
1 default value for any macro argument by following the name with
1 '=DEFLT'. You cannot define two macros with the same MACNAME
11 unless it has been subject to the '.purgem' directive (⇒
Purgem) between the two definitions. For example, these are all
1 valid '.macro' statements:
1
1 '.macro comm'
1 Begin the definition of a macro called 'comm', which takes no
1 arguments.
1
1 '.macro plus1 p, p1'
1 '.macro plus1 p p1'
1 Either statement begins the definition of a macro called
1 'plus1', which takes two arguments; within the macro
1 definition, write '\p' or '\p1' to evaluate the arguments.
1
1 '.macro reserve_str p1=0 p2'
1 Begin the definition of a macro called 'reserve_str', with two
1 arguments. The first argument has a default value, but not
1 the second. After the definition is complete, you can call
1 the macro either as 'reserve_str A,B' (with '\p1' evaluating
1 to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with
1 '\p1' evaluating as the default, in this case '0', and '\p2'
1 evaluating to B).
1
1 '.macro m p1:req, p2=0, p3:vararg'
1 Begin the definition of a macro called 'm', with at least
1 three arguments. The first argument must always have a value
1 specified, but not the second, which instead has a default
1 value. The third formal will get assigned all remaining
1 arguments specified at invocation time.
1
1 When you call a macro, you can specify the argument values
1 either by position, or by keyword. For example, 'sum 9,17' is
1 equivalent to 'sum to=17, from=9'.
1
1 Note that since each of the MACARGS can be an identifier exactly as
1 any other one permitted by the target architecture, there may be
1 occasional problems if the target hand-crafts special meanings to
1 certain characters when they occur in a special position. For
1 example, if the colon (':') is generally permitted to be part of a
1 symbol name, but the architecture specific code special-cases it
1 when occurring as the final character of a symbol (to denote a
1 label), then the macro parameter replacement code will have no way
1 of knowing that and consider the whole construct (including the
1 colon) an identifier, and check only this identifier for being the
1 subject to parameter substitution. So for example this macro
1 definition:
1
1 .macro label l
1 \l:
1 .endm
1
1 might not work as expected. Invoking 'label foo' might not create
1 a label called 'foo' but instead just insert the text '\l:' into
1 the assembler source, probably generating an error about an
1 unrecognised identifier.
1
1 Similarly problems might occur with the period character ('.')
1 which is often allowed inside opcode names (and hence identifier
1 names). So for example constructing a macro to build an opcode
1 from a base name and a length specifier like this:
1
1 .macro opcode base length
1 \base.\length
1 .endm
1
1 and invoking it as 'opcode store l' will not create a 'store.l'
1 instruction but instead generate some kind of error as the
1 assembler tries to interpret the text '\base.\length'.
1
1 There are several possible ways around this problem:
1
1 'Insert white space'
1 If it is possible to use white space characters then this is
1 the simplest solution. eg:
1
1 .macro label l
1 \l :
1 .endm
1
1 'Use '\()''
1 The string '\()' can be used to separate the end of a macro
1 argument from the following text. eg:
1
1 .macro opcode base length
1 \base\().\length
1 .endm
1
1 'Use the alternate macro syntax mode'
1 In the alternative macro syntax mode the ampersand character
1 ('&') can be used as a separator. eg:
1
1 .altmacro
1 .macro label l
1 l&:
1 .endm
1
1 Note: this problem of correctly identifying string parameters to
11 pseudo ops also applies to the identifiers used in '.irp' (⇒
Irp) and '.irpc' (⇒Irpc) as well.
1
1 '.endm'
1 Mark the end of a macro definition.
1
1 '.exitm'
1 Exit early from the current macro definition.
1
1 '\@'
1 'as' maintains a counter of how many macros it has executed in this
1 pseudo-variable; you can copy that number to your output with '\@',
1 but _only within a macro definition_.
1
1 'LOCAL NAME [ , ... ]'
1 _Warning: 'LOCAL' is only available if you select "alternate macro
1