David Wohlferd's patch to document more issues with basic asms

	* doc/extend.texi: Document more potential problems with basic asms.

From-SVN: r234343

2 files changed, 31 insertions, 11 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 328fde8..9aee1f0 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2016-03-16  David Wohlferd  <dw@LimeGreenSocks.com>
+            Bernd Schmidt  <bschmidt@redhat.com>
+
+	* doc/extend.texi: Document more potential problems with basic asms.
+
 2016-03-18  Bernd Schmidt  <bschmidt@redhat.com>
 
 	PR rtl-optimization/70278
@@ -42,7 +47,7 @@
 	define_constraint for "Q" and "T" constraints.
 
 2016-03-17  Evandro Menezes  <e.menezes@samsung.com>
-	
+
 	Tweak the pipeline model for Exynos M1
 
 	* config/aarch64/aarch64.c (exynosm1_tunings): 	Enable weak prefetching
@@ -227,19 +232,19 @@
 
 	PR rtl-optimization/69032
 	* sel-sched-ir.c (get_seqno_by_preds): Include both insn and head when
-	looping backwards over basic block insns. 
+	looping backwards over basic block insns.
 
 2016-03-15  Andrey Belevantsev  <abel@ispras.ru>
 
 	PR target/66660
 	* sel-sched-ir.c (merge_expr): Avoid changing the speculative pattern
-	to non-speculative when propagating trap bits. 
+	to non-speculative when propagating trap bits.
 
 2016-03-15  Andrey Belevantsev  <abel@ispras.ru>
 
 	PR rtl-optimization/63384
 	* sel-sched.c (invoke_aftermath_hooks): Do not decrease issue_more on
-	DEBUG_INSN_P insns. 
+	DEBUG_INSN_P insns.
 
 2016-03-15  Andrey Belevantsev  <abel@ispras.ru>
 
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 8fddb34..623a5d0 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -7452,10 +7452,10 @@ note that some assembler dialects use semicolons to start a comment.
 @end table
 
 @subsubheading Remarks
-Using extended @code{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:
+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:
 
 @itemize @bullet
 @item
@@ -7492,9 +7492,24 @@ assembly code when optimizing. This can lead to unexpected duplicate
 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