On 2/13/2016 8:00 PM, David Wohlferd wrote:
Fair enough. Committing what we can right now sounds like a good plan.
Attached is the doc patch, minus the proposed warning.
ChangeLog:
2016-02-19 David Wohlferd <d...@limegreensocks.com>
Bernd Schmidt <bschm...@redhat.com>
* doc/extend.texi: Doc basic asm behavior re clobbers.
dw
Index: extend.texi
===================================================================
--- extend.texi (revision 233367)
+++ extend.texi (working copy)
@@ -7458,7 +7458,8 @@
@end table
@subsubheading Remarks
-Using extended @code{asm} typically produces smaller, safer, and more
+Using extended @code{asm} (@pxref{Extended Asm}) typically produces smaller,
+safer, and more
efficient code, and in most cases it is a better solution than basic
@code{asm}. However, there are two situations where only basic @code{asm}
can be used:
@@ -7498,10 +7499,25 @@
symbol errors during compilation if your assembly code defines symbols or
labels.
-Since GCC does not parse the @var{AssemblerInstructions}, it has no
-visibility of any symbols it references. This may result in GCC discarding
-those symbols as unreferenced.
+@strong{Warning:} The C standards do not specify semantics for @code{asm},
+making it a potential source of incompatibilities between compilers. These
+incompatibilities may not produce compiler warnings/errors.
+GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which
+means there is no way to communicate to the compiler what is happening
+inside them. GCC has no visibility of symbols in the @code{asm} and may
+discard them as unreferenced. It also does not know about side effects of
+the assembler code, such as modifications to memory or registers. Unlike
+some compilers, GCC assumes that no changes to either memory or registers
+occur. This assumption may change in a future release.
+
+To avoid complications from future changes to the semantics and the
+compatibility issues between compilers, consider replacing basic @code{asm}
+with extended @code{asm}. See
+@uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert
+from basic asm to extended asm} for information about how to perform this
+conversion.
+
The compiler copies the assembler instructions in a basic @code{asm}
verbatim to the assembly language output file, without
processing dialects or any of the @samp{%} operators that are available with
@@ -7516,11 +7532,25 @@
Basic @code{asm} provides no
mechanism to provide different assembler strings for different dialects.
-Here is an example of basic @code{asm} for i386:
+Here is an example of top-level basic @code{asm} for i386 that defines an
+asm macro. That macro is then invoked from within a function using
+extended @code{asm}:
@example
-/* Note that this code will not compile with -masm=intel */
-#define DebugBreak() asm("int $3")
+/* Define macro at file scope with basic asm. */
+/* Add macro parameter p to eax. */
+asm (".macro testme p\n\t"
+ "addl $\\p, %eax\n\t"
+ ".endm");
+
+/* Use macro in function using extended asm. It needs
+ the "cc" clobber since the flags are changed and uses
+ the "a" constraint since it modifies eax. */
+int DoAdd (int value)
+@{
+ asm ("testme 5" : "+a" (value) : : "cc");
+ return value;
+@}
@end example
@node Extended Asm
