Update doc/extend.texi regarding asm memory clobbers

[Andreas Jaeger <aj at suse dot de>]

I found an old patch that started with this thread:
http://gcc.gnu.org/ml/gcc-patches/2002-03/msg00651.html

Since the problem just hit us again, I resurrected it and added an
example.

The patch was tested with make info.  Ok to commit?

Andreas

2004-01-16  Andreas Jaeger  <aj@suse.de>

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

============================================================
Index: gcc/doc/extend.texi
--- gcc/doc/extend.texi	7 Jan 2004 22:24:39 -0000	1.177
+++ gcc/doc/extend.texi	16 Jan 2004 14:46:59 -0000
@@ -4006,13 +4006,34 @@ represents the condition codes as a spec
 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 known 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{y} away:
+@example
+int foo (int *x)
+@{
+  int y = bar(x);
+  int r;
+  asm ("magic stuff accessing (%1)..."
+        "=&d" (r) : "a" (y), "m" (*y));
+  return r;     
+@}
+@end example
 
 You can put multiple assembler instructions together in a single
 @code{asm} template, separated by the characters normally used in assembly

-- 
 Andreas Jaeger, aj@suse.de, http://www.suse.de/~aj
  SuSE Linux AG, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126

Attachment: pgp00000.pgp
Description: PGP signature