Proposed doc update for Explicit Reg Vars 2/3

	* doc/extend.exp (Local Register Variables): Rewrite.

From-SVN: r229124

2 files changed, 70 insertions, 71 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 28cafa1..1c27b69 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,7 @@
+2015-10-21  David Wohlferd  <dw@LimeGreenSocks.com>
+
+	* doc/extend.exp (Local Register Variables): Rewrite.
+
 2015-10-21  Richard Sandiford  <richard.sandiford@arm.com>
 
 	* match.pd: Add rules to simplify ccos, ccosh, hypot, copysign
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index bdbf513..e54fe67 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -8473,7 +8473,7 @@ the assembler code should be @code{MYFUNC}.
 GNU C allows you to associate specific hardware registers with C 
 variables.  In almost all cases, allowing the compiler to assign
 registers produces the best code.  However under certain unusual
-circumstances,  more precise control over the variable storage is 
+circumstances, more precise control over the variable storage is 
 required.
 
 Both global and local variables can be associated with a register.  The
@@ -8492,68 +8492,79 @@ the two, as explained in the sections below.
 @cindex registers, global variables in
 @cindex registers, global allocation
 
-You can define a global register variable in GNU C like this:
+You can define a global register variable and associate it with a specified 
+register like this:
 
 @smallexample
-register int *foo asm ("a5");
+register int *foo asm ("r12");
 @end smallexample
 
 @noindent
-Here @code{a5} is the name of the register that should be used.  Choose a
-register that is normally saved and restored by function calls on your
-machine, so that library routines will not clobber it.
-
-Naturally the register name is CPU-dependent, so you need to
-conditionalize your program according to CPU type.  The register
-@code{a5} is a good choice on a 68000 for a variable of pointer
-type.  On machines with register windows, be sure to choose a ``global''
-register that is not affected magically by the function call mechanism.
+Here @code{r12} is the name of the register that should be used. Note that 
+this is the same syntax used for defining local register variables, but for 
+a global variable the declaration appears outside a function. The 
+@code{register} keyword is required, and cannot be combined with 
+@code{static}. The register name must be a valid register name for the
+target platform.
+
+Registers are a scarce resource on most systems and allowing the 
+compiler to manage their usage usually results in the best code. However, 
+under special circumstances it can make sense to reserve some globally.
+For example this may be useful in programs such as programming language 
+interpreters that have a couple of global variables that are accessed 
+very often.
+
+After defining a global register variable, for the current compilation
+unit:
 
-In addition, different operating systems on the same CPU may differ in how they
-name the registers; then you need additional conditionals.  For
-example, some 68000 operating systems call this register @code{%a5}.
+@itemize @bullet
+@item The register is reserved entirely for this use, and will not be 
+allocated for any other purpose.
+@item The register is not saved and restored by any functions.
+@item Stores into this register are never deleted even if they appear to be 
+dead, but references may be deleted, moved or simplified.
+@end itemize
+
+Note that these points @emph{only} apply to code that is compiled with the
+definition. The behavior of code that is merely linked in (for example 
+code from libraries) is not affected.
 
-Eventually there may be a way of asking the compiler to choose a register
-automatically, but first we need to figure out how it should choose and
-how to enable you to guide the choice.  No solution is evident.
+If you want to recompile source files that do not actually use your global 
+register variable so they do not use the specified register for any other 
+purpose, you need not actually add the global register declaration to 
+their source code. It suffices to specify the compiler option 
+@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the 
+register.
 
-Defining a global register variable in a certain register reserves that
-register entirely for this use, at least within the current compilation.
-The register is not allocated for any other purpose in the functions
-in the current compilation, and is not saved and restored by
-these functions.  Stores into this register are never deleted even if they
-appear to be dead, but references may be deleted or moved or
-simplified.
+@subsubheading Declaring the variable
+
+Global register variables can not have initial values, because an
+executable file has no means to supply initial contents for a register.
 
-It is not safe to access the global register variables from signal
-handlers, or from more than one thread of control, because the system
-library routines may temporarily use the register for other things (unless
-you recompile them specially for the task at hand).
+When selecting a register, choose one that is normally saved and 
+restored by function calls on your machine. This ensures that code
+which is unaware of this reservation (such as library routines) will 
+restore it before returning.
+
+On machines with register windows, be sure to choose a global
+register that is not affected magically by the function call mechanism.
+
+@subsubheading Using the variable
 
 @cindex @code{qsort}, and global register variables
-It is not safe for one function that uses a global register variable to
-call another such function @code{foo} by way of a third function
-@code{lose} that is compiled without knowledge of this variable (i.e.@: in a
-different source file in which the variable isn't declared).  This is
-because @code{lose} might save the register and put some other value there.
-For example, you can't expect a global register variable to be available in
-the comparison-function that you pass to @code{qsort}, since @code{qsort}
-might have put something else in that register.  (If you are prepared to
-recompile @code{qsort} with the same global register variable, you can
-solve this problem.)
-
-If you want to recompile @code{qsort} or other source files that do not
-actually use your global register variable, so that they do not use that
-register for any other purpose, then it suffices to specify the compiler
-option @option{-ffixed-@var{reg}}.  You need not actually add a global
-register declaration to their source code.
-
-A function that can alter the value of a global register variable cannot
-safely be called from a function compiled without this variable, because it
-could clobber the value the caller expects to find there on return.
-Therefore, the function that is the entry point into the part of the
-program that uses the global register variable must explicitly save and
-restore the value that belongs to its caller.
+When calling routines that are not aware of the reservation, be 
+cautious if those routines call back into code which uses them. As an 
+example, if you call the system library version of @code{qsort}, it may 
+clobber your registers during execution, but (if you have selected 
+appropriate registers) it will restore them before returning. However 
+it will @emph{not} restore them before calling @code{qsort}'s comparison 
+function. As a result, global values will not reliably be available to 
+the comparison function unless the @code{qsort} function itself is rebuilt.
+
+Similarly, it is not safe to access the global register variables from signal
+handlers or from more than one thread of control. Unless you recompile 
+them specially for the task at hand, the system library routines may 
+temporarily use the register for other things.
 
 @cindex register variable after @code{longjmp}
 @cindex global register after @code{longjmp}
@@ -8561,29 +8572,13 @@ restore the value that belongs to its caller.
 @findex longjmp
 @findex setjmp
 On most machines, @code{longjmp} restores to each global register
-variable the value it had at the time of the @code{setjmp}.  On some
+variable the value it had at the time of the @code{setjmp}. On some
 machines, however, @code{longjmp} does not change the value of global
-register variables.  To be portable, the function that called @code{setjmp}
+register variables. To be portable, the function that called @code{setjmp}
 should make other arrangements to save the values of the global register
-variables, and to restore them in a @code{longjmp}.  This way, the same
+variables, and to restore them in a @code{longjmp}. This way, the same
 thing happens regardless of what @code{longjmp} does.
 
-All global register variable declarations must precede all function
-definitions.  If such a declaration could appear after function
-definitions, the declaration would be too late to prevent the register from
-being used for other purposes in the preceding functions.
-
-Global register variables may not have initial values, because an
-executable file has no means to supply initial contents for a register.
-
-On the SPARC, there are reports that g3 @dots{} g7 are suitable
-registers, but certain library functions, such as @code{getwd}, as well
-as the subroutines for division and remainder, modify g3 and g4.  g1 and
-g2 are local temporaries.
-
-On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
-Of course, it does not do to use more than a few of those.
-
 @node Local Register Variables
 @subsubsection Specifying Registers for Local Variables
 @anchor{Local Reg Vars}