Begin the definition of a macro called @code{comm}, which takes no
arguments.
-@item .macro plus1 p, p1
+@item .macro plus1 p, p1
@itemx .macro plus1 p p1
Either statement begins the definition of a macro called @code{plus1},
which takes two arguments; within the macro definition, write
@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str
,@var{b}} (with @samp{\p1} evaluating as the default, in this case
@samp{0}, and @samp{\p2} evaluating to @var{b}).
-@end table
@item .macro m p1:req, p2=0, p3:vararg
Begin the definition of a macro called @code{m}, with at least three
position, or by keyword. For example, @samp{sum 9,17} is equivalent to
@samp{sum to=17, from=9}.
+@end table
+
Note that since each of the @var{macargs} 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 colon
+characters when they occur in a special position. For example, if the colon
(@code{:}) is generally permitted to be part of a symbol name, but the
-architecture specific code special-cases it when occuring as the final
+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. In this
-example, besides the potential of just separating identifier and colon
-by white space, using alternate macro syntax (@xref{Altmacro}.) and
-ampersand (@code{&}) as the character to separate literal text from macro
-parameters (or macro parameters from one another) would provide a way to
-achieve the same effect:
+identifier for being the subject to parameter substitution. So for example
+this macro definition:
+
+@example
+ .macro label l
+\l:
+ .endm
+@end example
+
+might not work as expected. Invoking @samp{label foo} might not create a label
+called @samp{foo} but instead just insert the text @samp{\l:} into the
+assembler source, probably generating an error about an unrecognised
+identifier.
+
+Similarly problems might occur with the period character (@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:
+
+@example
+ .macro opcode base length
+ \base.\length
+ .endm
+@end example
+
+and invoking it as @samp{opcode store l} will not create a @samp{store.l}
+instruction but instead generate some kind of error as the assembler tries to
+interpret the text @samp{\base.\length}.
+
+There are several possible ways around this problem:
+
+@table @code
+@item Insert white space
+If it is possible to use white space characters then this is the simplest
+solution. eg:
+
+@example
+ .macro label l
+\l :
+ .endm
+@end example
+
+@item Use @samp{\()}
+The string @samp{\()} can be used to separate the end of a macro argument from
+the following text. eg:
+
+@example
+ .macro opcode base length
+ \base\().\length
+ .endm
+@end example
+
+@item Use the alternate macro syntax mode
+In the alternative macro syntax mode the ampersand character (@samp{&}) can be
+used as a separator. eg:
@example
.altmacro
l&:
.endm
@end example
+@end table
-This applies identically to the identifiers used in @code{.irp} (@xref{Irp}.)
-and @code{.irpc} (@xref{Irpc}.).
+Note - this problem of correctly identifying string parameters to pseudo ops
+also applies to the identifiers used in @code{.irp} (@xref{Irp}.)
+and @code{.irpc} (@xref{Irpc}.) as well.
@item .endm
@cindex @code{endm} directive
projects / binutils-gdb.git / commitdiff