Patch 2/3 is the update for the Global Register Variables page (attached).
Reviewing this patch is going to be difficult.
It's a lot easier to review a patch that just has a few lines of text
being added. However, this leads to 'chunky' docs with a bunch of
disjointed paragraphs (which is what this page has now). Eventually,
someone needs to take the whole thing, and rearrange, reformat and
reorganize it. Which is what this patch does.
So there isn't any new content (except the part recently removed from
asm labels about statics), just the old content rephrased and
reformatted. There is, however, some decidedly unhelpful text that got
removed (paraphrasing):
- There are unsourced, unsubstantiated reports that on some platforms,
certain things might or might not work.
- Eventually the compiler may work differently than it does now.
Argh! Who thinks this stuff is helpful? And while it was painful, I
kept in the part that says "when specifying register names, make sure
they are really register names."
As for the review, perhaps reading the html is easier than reading the
patch?
Here's the current text:
https://gcc.gnu.org/onlinedocs/gcc/Global-Reg-Vars.html
And here's the new:
http://limegreensocks.com/gcc/Global-Register-Variables.html
dw
Index: extend.texi
===================================================================
--- extend.texi (revision 228690)
+++ extend.texi (working copy)
@@ -8506,7 +8506,8 @@
@cindex global register variables
@cindex registers, global variables in
-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");
@@ -8513,62 +8514,77 @@
@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. 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 limited 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 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. 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
+
+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.
+
+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}
@@ -8582,22 +8598,6 @@
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 Reg Vars
@subsubsection Specifying Registers for Local Variables
@cindex local variables, specifying registers
