inline-asm: Improve documentation of "asm constexpr".

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.

diff --git a/gcc/cp/parser.cc b/gcc/cp/parser.cc
index c2b81fc281a80ba8ad89924ff8d5268306d7f478..94e8e11e39894c2f175b0ff96195cda641578422 100644 (file)
--- 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 5e40cf8387bbd46916233bc3cbd8b3eb528f3125..6797efc0bb40e661927e8dc569974f4e1f66a0de 100644 (file)
--- 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
-
-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}
+@subsection C++11 Constant Expressions instead of String Literals
+
+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"; @}