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
@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}
@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}
projects / gcc.git / commitdiff