extend.texi (Extended Asm): Clarify memory clobber.

2004-01-21  Andreas Jaeger  <aj@suse.de>
	    Michael Matz  <matz@suse.de>

	* doc/extend.texi (Extended Asm): Clarify memory clobber.

Co-Authored-By: Michael Matz <matz@suse.de>
From-SVN: r76291

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 8c4f7f2ef1bc0517a0fb51a2e07703dc1ad8032e..bc3aa77c9eb1830e80b01d8ab1d1bd45fd9fc191 100644 (file)
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2004-01-21  Andreas Jaeger  <aj@suse.de>
+           Michael Matz  <matz@suse.de>
+
+       * doc/extend.texi (Extended Asm): Clarify memory clobber.
+
 2004-01-21  Ralf Corsepius  <corsepiu@faw.uni-ulm.de>
 
        PR target/13073

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index f2aca2abd81f57d0d2b386e9a392e457be15893d..4d587c715f7bb8cfa4961a10cfa786e414e51845 100644 (file)
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3844,13 +3844,35 @@ represents the condition codes as a specific hardware register;
 condition code is handled differently, and specifying @samp{cc} has no
 effect.  But it is valid no matter what the machine.
 
-If your assembler instruction modifies memory in an unpredictable
+If your assembler instructions access memory in an unpredictable
 fashion, add @samp{memory} to the list of clobbered registers.  This
-will cause GCC to not keep memory values cached in registers across
-the assembler instruction.  You will also want to add the
-@code{volatile} keyword if the memory affected is not listed in the
-inputs or outputs of the @code{asm}, as the @samp{memory} clobber does
-not count as a side-effect of the @code{asm}.
+will cause GCC to not keep memory values cached in registers across the
+assembler instruction and not optimize stores or loads to that memory.
+You will also want to add the @code{volatile} keyword if the memory
+affected is not listed in the inputs or outputs of the @code{asm}, as
+the @samp{memory} clobber does not count as a side-effect of the
+@code{asm}.  If you know how large the accessed memory is, you can add
+it as input or output but if this is not known, you should add
+@samp{memory}.  As an example, if you access ten bytes of a string, you
+can use a memory input like:
+
+@example
+@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
+@end example
+
+Note that in the following example the memory input is necessary,
+otherwise GCC might optimize the store to @code{x} away:
+@example
+int foo ()
+@{
+  int x = 42;
+  int *y = &x;
+  int result;
+  asm ("magic stuff accessing an 'int' pointed to by '%1'"
+        "=&d" (r) : "a" (y), "m" (*y));
+  return result;     
+@}
+@end example
 
 You can put multiple assembler instructions together in a single
 @code{asm} template, separated by the characters normally used in assembly