extend.texi: Improve documentation of volatile asms.

	* extend.texi: Improve documentation of volatile asms.

	* c-tree.texi: Fix thinko.
	* gcc.texi: Likewise.

Co-Authored-By: Richard Henderson <rth@redhat.com>

From-SVN: r41712

gcc/ChangeLog

+2001-04-30  Mark Mitchell  <mark@codesourcery.com>
+            Richard Henderson  <rth@redhat.com>
+	
+	* extend.texi: Improve documentation of volatile asms.
+	
+2001-04-30  Mark Mitchell  <mark@codesourcery.com>
+
+	* c-tree.texi: Fix thinko.
+	* gcc.texi: Likewise.
+
 2001-04-30  Richard Henderson  <rth@redhat.com>
 
 	* c-common.c (c_promoting_integer_type_p): New function, from the

gcc/c-tree.texi

@@ -32,11 +32,10 @@ Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below).  A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
+any later version published by the Free Software Foundation; with no
+invariant sections, the Front-Cover texts being (a) (see below), and
+with the Back-Cover Texts being (b) (see below).  A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
 
 (a) The FSF's Front-Cover Text is:
 

gcc/extend.texi

@@ -3052,23 +3052,38 @@ the @code{asm}.  For example:
 @noindent
 If you write an @code{asm} instruction with no outputs, GNU CC will know
 the instruction has side-effects and will not delete the instruction or
-move it outside of loops.  If the side-effects of your instruction are
-not purely external, but will affect variables in your program in ways
-other than reading the inputs and clobbering the specified registers or
-memory, you should write the @code{volatile} keyword to prevent future
-versions of GNU CC from moving the instruction around within a core
-region.
+move it outside of loops.
 
-An @code{asm} instruction without any operands or clobbers (an ``old
-style'' @code{asm}) will not be deleted or moved significantly,
-regardless, unless it is unreachable, the same way as if you had
-written a @code{volatile} keyword.
+The @code{volatile} keyword indicates that the instruction has
+important side-effects.  GCC will not delete a volatile @code{asm} if
+it is reachable.  (The instruction can still be deleted if GCC can
+prove that control-flow will never reach the location of the
+instruction.)  In addition, GCC will not reschedule instructions
+across a volatile @code{asm} instruction.  For example:
+
+@example
+(volatile int *)addr = foo;
+asm volatile ("eieio" : : );
+@end example
+
+@noindent 
+Assume @code{addr} contains the address of a memory mapped device
+register.  The PowerPC @code{eieio} instruction (Enforce In-order
+Execution of I/O) tells the cpu to make sure that the store to that
+device register happens before it issues any other I/O.
 
 Note that even a volatile @code{asm} instruction can be moved in ways
 that appear insignificant to the compiler, such as across jump
 instructions.  You can't expect a sequence of volatile @code{asm}
 instructions to remain perfectly consecutive.  If you want consecutive
-output, use a single @code{asm}.
+output, use a single @code{asm}.  Also, GCC will perform some
+optimizations across a volatile @code{asm} instruction; GCC does not
+``forget everything'' when it encounters a volatile @code{asm}
+instruction the way some other compilers do.
+
+An @code{asm} instruction without any operands or clobbers (an ``old
+style'' @code{asm}) will be treated identically to a volatile
+@code{asm} instruction.
 
 It is a natural idea to look for a way to give access to the condition
 code left by the assembler instruction.  However, when we attempted to

gcc/gcc.texi

@@ -125,10 +125,10 @@ Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
 any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'', the Front-Cover
-texts being (a) (see below), and with the Back-Cover Texts being (b)
-(see below).  A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
+Invariant Sections being ``GNU General Public License'' and ``Funding
+Free Software'', the Front-Cover texts being (a) (see below), and with
+the Back-Cover Texts being (b) (see below).  A copy of the license is
+included in the section entitled ``GNU Free Documentation License''.
 
 (a) The FSF's Front-Cover Text is: