From cbb5c732c20e385bf3d0bf04b533b22281a7dde2 Mon Sep 17 00:00:00 2001 From: David Wohlferd Date: Wed, 21 Oct 2015 15:39:08 +0000 Subject: Proposed doc update for Explicit Reg Vars 2/3 * doc/extend.exp (Local Register Variables): Rewrite. From-SVN: r229124 --- gcc/ChangeLog | 4 ++ gcc/doc/extend.texi | 137 +++++++++++++++++++++++++--------------------------- 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 + + * doc/extend.exp (Local Register Variables): Rewrite. + 2015-10-21 Richard Sandiford * 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} -- cgit v1.1