From ed3b601b7a86b816e048fde17572eb8220171282 Mon Sep 17 00:00:00 2001 From: nickc Date: Fri, 8 Sep 2006 16:25:46 +0000 Subject: [PATCH] PR gas/3129 * doc/as.texinfo (Macro): Improve documentation about separating macro arguments from following text. --- gas/ChangeLog | 6 +++++ gas/doc/as.texinfo | 76 +++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 70 insertions(+), 12 deletions(-) diff --git a/gas/ChangeLog b/gas/ChangeLog index b5dd1723aa..2062dd8ca5 100644 --- a/gas/ChangeLog +++ b/gas/ChangeLog @@ -1,3 +1,9 @@ +2006-09-08 Nick Clifton + + PR gas/3129 + * doc/as.texinfo (Macro): Improve documentation about separating + macro arguments from following text. + 2006-09-08 Paul Brook * config/tc-arm.c (insns): Allow ARM IT pseudo-insn on all cores. diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo index 494381fdfc..150ef30ac8 100644 --- a/gas/doc/as.texinfo +++ b/gas/doc/as.texinfo @@ -4987,7 +4987,7 @@ definitions. For example, these are all valid @code{.macro} statements: 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 @@ -5001,7 +5001,6 @@ After the definition is complete, you can call the macro either as @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 @@ -5013,21 +5012,72 @@ When you call a macro, you can specify the argument values either by 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 @@ -5035,9 +5085,11 @@ achieve the same effect: 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 -- 2.11.0