This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Proposed doc update for Explicit Reg Vars 2/3



Line too long. I know quite a bit of doc does that, but that's no excuse :-)

Reduced to < 79.

+Registers can be a limited resource on some systems and allowing the
They are a limited resource on almost all systems.  "Scarce resource"?

"Scarce" it is. I've left the rest alone for the moment, but how would you feel about:

"Registers are a scarce resource on most systems and allowing the"

+After defining a global register variable, for the duration of
+the current compilation:
It's probably better to say "for the current compilation unit"?  There now
is LTO and whatnot.

Changed to "for the current compilation unit".

+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.
This isn't true anymore, not even with -fno-toplevel-reorder or -O0.

I'm going to interpret this as a recommendation to remove this text, rather than just an FYI. Done.

+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.
The compiler also warns, possibly for the unlikely case that the user has
not read the documentation.

I'm going to interpret this comment as just an FYI, and NOT something that should be added to the docs.

I've attached the new patch for the Globals. For review purposes, you can just diff it with the previous one. Viewed that way, the changes are pretty minor.

dw
Index: extend.texi
===================================================================
--- extend.texi	(revision 229108)
+++ extend.texi	(working copy)
@@ -8473,7 +8473,7 @@
 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,69 +8492,80 @@
 @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.
+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.
 
-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.
+Registers can be a scarce resource on some 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.
 
-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 current compilation
+unit:
 
-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. The behavior of code that is merely linked in (for example 
+code from libraries) is not affected.
 
-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 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.
 
+@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.
+
+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.)
+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.
 
-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.
+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.
 
-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.
-
 @cindex register variable after @code{longjmp}
 @cindex global register after @code{longjmp}
 @cindex value after @code{longjmp}
@@ -8561,29 +8572,13 @@
 @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}

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]