[DOC Patch] Explicit Register Variables

[David Wohlferd <dw at LimeGreenSocks dot com>]

I don't have permissions to commit this patch, but I do have a release 
on file with the FSF.

Problem description:
The text for using Explicit Register Variables is confusing, redundant, 
and fails to make certain essential information clear.

Some specific problems:
- There is no reason to call this topic "Explicit Reg Vars" instead of 
"Explicit Register Variables."
- Putting text on the "Explicit Register Variables" menu page (instead 
of the Global or Local subpages) is redundant, since any text that 
describes the usage of Global or Local register variables will have to 
be repeated on the individual subpages.
- Vague promises of features that may some day be available are not 
useful in documentation ("Eventually there may be a way of asking the 
compiler to").
- Vague descriptions of things that "are reported" to work on certain 
platforms are not useful ("On the SPARC, there are reports that").
- Describing Local Register Variables as "sometimes convenient for use 
with the extended asm feature" misses the point that this is in fact the 
ONLY supported use for Local Register Variables.
- Unambiguous statements such as "The following uses are explicitly 
/not/ supported" when describing things such as calling Basic asm 
discourage people from attempting to misuse the feature.

ChangeLog:
2014-06-30  David Wohlferd  <dw@LimeGreenSocks.com>

        * doc/extend.texi (Explicit Reg Vars): Rewrite and clarify.
        * doc/implement-c.texi (Hints implementation): Use new name.

dw

Index: extend.texi
===================================================================
--- extend.texi	(revision 210997)
+++ extend.texi	(working copy)
@@ -6234,7 +6234,8 @@
 * Extended Asm::       Inline assembler with operands.
 * Constraints::        Constraints for @code{asm} operands
 * Asm Labels::         Specifying the assembler name to use for a C symbol.
-* Explicit Reg Vars::  Defining variables residing in specified registers.
+* Explicit Register Variables::  Defining variables residing in specified 
+                       registers.
 * Size of an asm::     How GCC calculates the size of an @code{asm} block.
 @end menu
 
@@ -6723,8 +6724,8 @@
 list as many alternates as the @code{asm} statement allows, you will permit 
 the optimizers to produce the best possible code. If you must use a specific
 register, but your Machine Constraints do not provide sufficient 
-control to select the specific register you want, Local Reg Vars may provide 
-a solution (@pxref{Local Reg Vars}).
+control to select the specific register you want, Local Register Variables 
+may provide a solution (@pxref{Local Register Variables}).
 
 @emph{cvariablename}
 @*
@@ -6865,8 +6866,8 @@
 method based on the current context. Input constraints may not begin with 
 either "=" or "+". If you must use a specific register, but your Machine
 Constraints do not provide sufficient control to select the specific 
-register you want, Local Reg Vars may provide a solution 
-(@pxref{Local Reg Vars}).
+register you want, Local Register Variables may provide a solution 
+(@pxref{Local Register Variables}).
 
 Input constraints can also be digits (for example, @code{"0"}). This indicates 
 that the specified input will be in the same place as the output constraint 
@@ -6952,7 +6953,8 @@
 Clobber descriptions may not in any way overlap with an input or output 
 operand. For example, you may not have an operand describing a register class 
 with one member when listing that register in the clobber list. Variables 
-declared to live in specific registers (@pxref{Explicit Reg Vars}), and used 
+declared to live in specific registers (@pxref{Explicit Register Variables}), 
+and used 
 as @code{asm} input or output operands, must have no part mentioned in the 
 clobber description. In particular, there is no way to specify that input 
 operands get modified without also specifying them as output operands.
@@ -7290,7 +7292,7 @@
 It does not make sense to use this feature with a non-static local
 variable since such variables do not have assembler names.  If you are
 trying to put the variable in a particular register, see @ref{Explicit
-Reg Vars}.  GCC presently accepts such code with a warning, but will
+Register Variables}.  GCC presently accepts such code with a warning, but will
 probably be changed to issue an error, rather than a warning, in the
 future.
 
@@ -7312,197 +7314,128 @@
 does not as yet have the ability to store static variables in registers.
 Perhaps that will be added.
 
-@node Explicit Reg Vars
+@node Explicit Register Variables
 @subsection Variables in Specified Registers
 @cindex explicit register variables
 @cindex variables in specified registers
 @cindex specified registers
-@cindex registers, global allocation
 
-GNU C allows you to put a few global variables into specified hardware
-registers.  You can also specify the register in which an ordinary
-register variable should be allocated.
+GNU C allows you to associate specific hardware registers with ``C'' 
+variables.
 
-@itemize @bullet
-@item
-Global register variables reserve registers throughout the program.
-This may be useful in programs such as programming language
-interpreters that have a couple of global variables that are accessed
-very often.
-
-@item
-Local register variables in specific registers do not reserve the
-registers, except at the point where they are used as input or output
-operands in an @code{asm} statement and the @code{asm} statement itself is
-not deleted.  The compiler's data flow analysis is capable of determining
-where the specified registers contain live values, and where they are
-available for other uses.  Stores into local register variables may be deleted
-when they appear to be dead according to dataflow analysis.  References
-to local register variables may be deleted or moved or simplified.
-
-These local variables are sometimes convenient for use with the extended
-@code{asm} feature (@pxref{Extended Asm}), if you want to write one
-output of the assembler instruction directly into a particular register.
-(This works provided the register you specify fits the constraints
-specified for that operand in the @code{asm}.)
-@end itemize
-
 @menu
-* Global Reg Vars::
-* Local Reg Vars::
+* Global Register Variables::   Reserve registers for the entire program.
+* Local Register Variables::    Specify registers when calling Extended Asm.
 @end menu
 
-@node Global Reg Vars
+@node Global Register Variables
 @subsubsection Defining Global Register Variables
 @cindex global register variables
 @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 with a specified register 
+like this:
 
 @smallexample
 register int *foo asm ("a5");
 @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.
+Here @code{a5} 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. 
 
-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.
+While registers can be a limited resource on some systems, 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.
 
-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}.
+After defining a global register variable, for the duration of 
+the current compilation:
 
-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.
+@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
 
-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.
+Note that these points @emph{only} apply to code that is compiled with the
+definition, not code such as libraries that is merely linked in.
 
-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).
+If you want to recompile source files that do not
+actually use your global register variable so they do not use a 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}).
 
+Some implementation details:
+
+@itemize @bullet
+@item All global register variable declarations must precede all function
+definitions.  If such a declaration appears after function definitions, 
+the declaration would be too late to prevent the register from being used 
+for other purposes in the preceding functions.
+@item Global register variables can not have initial values, because an
+executable file has no means to supply initial contents for a register.
+@item When selecting a register, choose one that is normally saved and 
+restored by function calls on your machine.  This ensures library routines 
+which are unaware of this reservation will restore it before returning.
 @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.
-
+@item When calling routines that are not aware of the reservation, be 
+cautious if those routines call back into code which does.  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 the @var{compar} function.  As a result, global values 
+will not reliably be available to the @var{compar} function unless the 
+@code{qsort} function is rebuilt.
+@item On machines with register windows, be sure to choose a global
+register that is not affected magically by the function call mechanism.
+@item 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}
 @cindex value after @code{longjmp}
 @findex longjmp
 @findex setjmp
-On most machines, @code{longjmp} restores to each global register
+@item On most machines, @code{longjmp} restores to each global register
 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}
 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
 thing happens regardless of what @code{longjmp} does.
+@end itemize
 
-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 Reg Vars
+@node Local Register Variables
 @subsubsection Specifying Registers for Local Variables
 @cindex local variables, specifying registers
 @cindex specifying registers for local variables
 @cindex registers for local variables
 
-You can define a local register variable with a specified register
-like this:
+You can define a local register variable with a specified register like this:
 
 @smallexample
 register int *foo asm ("a5");
 @end smallexample
 
-@noindent
-Here @code{a5} is the name of the register that should be used.  Note
-that this is the same syntax used for defining global register
-variables, but for a local variable it appears within a function.
+Here @code{a5} is the name of the register that should be used.  Note that 
+this is the same syntax used for defining global register variables, but 
+for a local variable the declaration appears within a function.
 
-Naturally the register name is cpu-dependent, but this is not a
-problem, since specific registers are most often useful with explicit
-assembler instructions (@pxref{Extended Asm}).  Both of these things
-generally require that you conditionalize your program according to
-cpu type.
-
-In addition, operating systems on one type of 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}.
-
-Defining such a register variable does not reserve the register; it
-remains available for other uses in places where flow control determines
-the variable's value is not live.
-
-This option does not guarantee that GCC generates code that has
-this variable in the register you specify at all times.  You may not
-code an explicit reference to this register in the @emph{assembler
-instruction template} part of an @code{asm} statement and assume it
-always refers to this variable.  However, using the variable as an
-@code{asm} @emph{operand} guarantees that the specified register is used
-for the operand.
-
-Stores into local register variables may be deleted when they appear to be dead
-according to dataflow analysis.  References to local register variables may
-be deleted or moved or simplified.
-
-As with global register variables, it is recommended that you choose a
-register that is normally saved and restored by function calls on
-your machine, so that library routines will not clobber it.  
-
-Sometimes when writing inline @code{asm} code, you need to make an operand be a 
-specific register, but there's no matching constraint letter for that 
-register. To force the operand into that register, create a local variable 
+The only generally supported use for this feature is to specify registers 
+for input and output operands when calling Extended @code{asm} 
+(@pxref{Extended Asm}). This may be necessary if the constraints for a 
+particular machine don't provide sufficient control to select the desired 
+register.  To force an operand into a register, create a local variable 
 and specify the register in the variable's declaration. Then use the local 
-variable for the asm operand and specify any constraint letter that matches 
-the register:
+variable for the @code{asm} operand and specify any constraint letter that 
+matches the register:
 
 @smallexample
 register int *p1 asm ("r0") = @dots{};
@@ -7511,11 +7444,11 @@
 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
 @end smallexample
 
-@emph{Warning:} In the above example, be aware that a register (for example r0) can be 
-call-clobbered by subsequent code, including function calls and library calls 
-for arithmetic operators on other variables (for example the initialization 
-of p2). In this case, use temporary variables for expressions between the 
-register assignments:
+@emph{Warning:} In the above example, be aware that a register (for example 
+@code{r0}) can be call-clobbered by subsequent code, including function 
+calls and library calls for arithmetic operators on other variables (for 
+example the initialization of @code{p2}). In this case, use temporary 
+variables for expressions between the register assignments:
 
 @smallexample
 int t1 = @dots{};
@@ -7525,6 +7458,38 @@
 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
 @end smallexample
 
+The following uses are explicitly @emph{not} supported. If they appear to 
+work, it is only happenstance, and will likely break in a future release:
+
+@itemize @bullet
+@item Passing parameters to or from Basic @code{asm}.
+@item Passing parameters to or from routines written in assembler.
+@item Attempting to optimize code by manually specifying registers.
+@end itemize
+
+Other implementation details:
+
+@itemize @bullet
+@item Register names are cpu dependent and can change depending on the 
+operating system.
+@item Defining a register variable does not reserve the register; it 
+remains available for other uses in places where flow control determines 
+the variable's value is not live. As a result, you may not code an explicit 
+reference to this register in the @emph{AssemblerTemplate} part of an 
+@code{asm} statement (or the AssemblerInstructions of a Basic @code{asm}
+instruction) and assume it always refers to this variable.
+@item Stores into local register variables may be deleted when they appear 
+to be dead according to dataflow analysis.  References to local register 
+variables may be deleted, moved, or simplified.
+@item As with global register variables, it is recommended that you choose 
+a register that is normally saved and restored by function calls on your 
+machine, so that library routines will not clobber it.
+@item On the MIPS platform, there is related use for local register 
+variables with slightly different characteristics (@pxref{MIPS Coprocessors,, 
+Defining coprocessor specifics for MIPS targets, gccint, 
+GNU Compiler Collection (GCC) Internals}).
+@end itemize
+
 @node Size of an asm
 @subsection Size of an @code{asm}
 
Index: implement-c.texi
===================================================================
--- implement-c.texi	(revision 210997)
+++ implement-c.texi	(working copy)
@@ -427,7 +427,7 @@
 @itemize @bullet
 @item
 When used as part of the register variable extension, see
-@ref{Explicit Reg Vars}.
+@ref{Explicit Register Variables}.
 
 @item
 When @option{-O0} is in use, the compiler allocates distinct stack