procyberian/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
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.
This commit is contained in:
Sandra Loosemore 2025-03-08 16:25:09 +00:00
parent b360d4aafc
commit dff0592945
2 changed files with 40 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
gcc/cp/parser.cc
View file

@ -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 `('. */

58
gcc/doc/extend.texi
View file

@ -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"; @}