Re: AW: Wonly-top-basic-asm

[David Wohlferd <dw at LimeGreenSocks dot com>]

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  <dw@LimeGreenSocks.com>
        Bernd Schmidt  <bschmidt@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