While working on an adjacent documentation fix, I noticed that the
documentation for the gnu++11 "asm constexpr" feature was very
confusing, in some cases being attached to parts of the asm syntax
that are not otherwise required to be string literals, and missing from
other parts of the syntax that are. I've checked what the C++ parser
actually does and fixed the documentation to match, also improving it
to use correct markup and to be more explicit and less implementor-speaky.
gcc/cp/ChangeLog
* parser.cc (cp_parser_asm_definition): Make comment more explicit.
(cp_parser_asm_operand_list): Likewise. Also correct the comment
block at the top of the function to reflect reality.
gcc/ChangeLog
* doc/extend.texi (Basic Asm): Document that AssemblerInstructions
can be an asm constexpr.
(Extended Asm): Move the notes about asm constexprs for
AssemblerTemplate and Clobbers to the corresponding subsections.
Remove the notes for OutputOperands and InputOperands and reword
misleading descriptions of the list item syntax. Note that
constraint strings can be asm constexprs.
(Asm constexprs): Use "title case" for subsection name. Be
explicit about what parts of the asm syntax this applies to and
that the parentheses are required. Correct markup and terminology.
---
gcc/cp/parser.cc | 8 +++----
gcc/doc/extend.texi | 58 ++++++++++++++++++++++++++++-----------------
2 files changed, 40 insertions(+), 26 deletions(-)
diff --git a/gcc/cp/parser.cc b/gcc/cp/parser.cc
index c2b81fc281a..94e8e11e398 100644
--- a/gcc/cp/parser.cc
+++ b/gcc/cp/parser.cc
@@ -23420,7 +23420,7 @@ cp_parser_asm_definition (cp_parser* parser)
/* Look for the opening `('. */
if (!cp_parser_require (parser, CPP_OPEN_PAREN, RT_OPEN_PAREN))
return;
- /* Look for the string. */
+ /* Look for the asm template string. */
tree string = cp_parser_asm_string_expression (parser);
if (string == error_mark_node)
{
@@ -30310,12 +30310,12 @@ cp_parser_asm_specification_opt (cp_parser* parser)
asm-operand:
asm-string-expr ( expression )
- [ asm-string-expr ] asm-string-expr ( expression )
+ [ identifier ] asm-string-expr ( expression )
Returns a TREE_LIST representing the operands. The TREE_VALUE of
each node is the expression. The TREE_PURPOSE is itself a
TREE_LIST whose TREE_PURPOSE is a STRING_CST for the bracketed
- string-literal (or NULL_TREE if not present) and whose TREE_VALUE
+ identifier (or NULL_TREE if not present) and whose TREE_VALUE
is a STRING_CST for the string literal before the parenthesis. Returns
ERROR_MARK_NODE if any of the operands are invalid. */
@@ -30343,7 +30343,7 @@ cp_parser_asm_operand_list (cp_parser* parser)
}
else
name = NULL_TREE;
- /* Look for the string. */
+ /* Look for the constraint string. */
tree string_literal = cp_parser_asm_string_expression (parser);
/* Look for the `('. */
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 5e40cf8387b..6797efc0bb4 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -10984,10 +10984,14 @@ of an asm}).
@table @var
@item AssemblerInstructions
-This is a literal string that specifies the assembler code. The string can
-contain any instructions recognized by the assembler, including directives.
-GCC does not parse the assembler instructions themselves and
-does not know what they mean or even whether they are valid assembler input.
+This is a literal string that specifies the assembler code.
+In C++ with @option{-std=gnu++11} or later, it can
+also be a constant expression inside parentheses (see @ref{Asm constexprs}).
+
+The string can contain any instructions recognized by the assembler,
+including directives. GCC does not parse the assembler instructions
+themselves and does not know what they mean or even whether they are
+valid assembler input.
You may place multiple assembler instructions together in a single @code{asm}
string, separated by the characters normally used in assembly code for the
@@ -11128,27 +11132,22 @@ perform a jump to one of the labels listed in the
@var{GotoLabels}.
@item AssemblerTemplate
This is a literal string that is the template for the assembler code. It is a
combination of fixed text and tokens that refer to the input, output,
-and goto parameters. @xref{AssemblerTemplate}. With gnu++11 or later it can
-also be a constant expression inside parens (see @ref{Asm constexprs}).
+and goto parameters. @xref{AssemblerTemplate}.
@item OutputOperands
-A comma-separated list of the C variables modified by the instructions in the
-@var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}.
-With gnu++11 or later the strings can also be constant expressions inside
parens
-(see @ref{Asm constexprs})
+A comma-separated list describing the C variables modified by the
+instructions in the @var{AssemblerTemplate}. An empty list is permitted.
+@xref{OutputOperands}.
@item InputOperands
-A comma-separated list of C expressions read by the instructions in the
-@var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}.
-With gnu++11 or later the strings can also be constant expressions inside
parens
-(see @ref{Asm constexprs})
+A comma-separated list describing the C expressions read by the
+instructions in the @var{AssemblerTemplate}. An empty list is permitted.
+@xref{InputOperands}.
@item Clobbers
A comma-separated list of registers or other values changed by the
@var{AssemblerTemplate}, beyond those listed as outputs.
An empty list is permitted. @xref{Clobbers and Scratch Registers}.
-With gnu++11 or later the strings can also be constant expressions inside
parens
-(see @ref{Asm constexprs})
@item GotoLabels
When you are using the @code{goto} form of @code{asm}, this section contains
@@ -11330,6 +11329,9 @@ Using @samp{%=}
@cindex @code{asm} assembler template
An assembler template is a literal string containing assembler instructions.
+In C++ with @option{-std=gnu++11} or later, the assembler template can
+also be a constant expression inside parentheses (see @ref{Asm constexprs}).
+
The compiler replaces tokens in the template that refer
to inputs, outputs, and goto labels,
and then outputs the resulting string to the assembler. The
@@ -11478,7 +11480,7 @@ brackets @samp{[]} around the @var{asmSymbolicName} are
required both
in the operand specification and references to the operand in the assembler
template, i.e.@: @samp{%[Value]}.
The scope of the name is the @code{asm} statement
-that contains the definition. Any valid C variable name is acceptable,
+that contains the definition. Any valid C identifier is acceptable,
including names already defined in the surrounding code. No two operands
within the same @code{asm} statement can use the same symbolic name.
@@ -11491,6 +11493,8 @@ three output operands, use @samp{%0} in the template to
refer to the first,
@item constraint
A string constant specifying constraints on the placement of the operand;
@xref{Constraints}, for details.
+In C++ with @option{-std=gnu++11} or later, the constraint can
+also be a constant expression inside parentheses (see @ref{Asm constexprs}).
Output constraints must begin with either @samp{=} (a variable overwriting an
existing value) or @samp{+} (when reading and writing). When using
@@ -11768,7 +11772,7 @@ brackets @samp{[]} around the @var{asmSymbolicName} are
required both
in the operand specification and references to the operand in the assembler
template, i.e.@: @samp{%[Value]}.
The scope of the name is the @code{asm} statement
-that contains the definition. Any valid C variable name is acceptable,
+that contains the definition. Any valid C identifier is acceptable,
including names already defined in the surrounding code. No two operands
within the same @code{asm} statement can use the same symbolic name.
@@ -11782,6 +11786,8 @@ use @samp{%2} in the template to refer to the first
input operand,
@item constraint
A string constant specifying constraints on the placement of the operand;
@xref{Constraints}, for details.
+In C++ with @option{-std=gnu++11} or later, the constraint can
+also be a constant expression inside parentheses (see @ref{Asm constexprs}).
Input constraint strings may not begin with either @samp{=} or @samp{+}.
When you list more than one possible location (for example, @samp{"irm"}),
@@ -11871,6 +11877,8 @@ In order to inform the compiler of these changes, list
them in the clobber
list. Clobber list items are either register names or the special clobbers
(listed below). Each clobber list item is a string constant
enclosed in double quotes and separated by commas.
+In C++ with @option{-std=gnu++11} or later, a clobber list item can
+also be a constant expression inside parentheses (see @ref{Asm constexprs}).
Clobber descriptions may not in any way overlap with an input or output
operand. For example, you may not have an operand describing a register class
@@ -12707,15 +12715,21 @@ The list below describes the supported modifiers and
their effects for the SH fa
@raisesections
@node Asm constexprs
-@subsection C++11 constant expressions instead of string literals
+@subsection C++11 Constant Expressions instead of String Literals
-With gnu++11 or later the string can also be a compile time constant expression
-inside parens. The constant expression can return a container with data and
size
-member functions, following similar rules as C++26 @code{static_assert}
+In C++ with @option{-std=gnu++11} or later, strings that appear in asm
+syntax---specifically, the assembler template, constraints, and
+clobbers---can be specified as parenthesized compile-time constant
+expressions as well as by string literals. The parentheses around such
+an expression are a required part of the syntax. The constant expression
+can return a container with @code{data ()} and @code{size ()}
+member functions, following similar rules as the C++26 @code{static_assert}
message. Any string is converted to the character set of the source code.
When this feature is available the @code{__GXX_CONSTEXPR_ASM__} preprocessor
macro is predefined.
+This extension is supported for both the basic and extended asm syntax.
+
@example
#include <string>
constexpr std::string_view genfoo() @{ return "foo"; @}
--
2.34.1
