Patch 3/3 is the update for the Local Register Variables page (attached).
This patch starts with a question. Looking at bug
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=64951 (register variable
with template function) is this a bug that will be fixed? Or a
limitation that should be doc'ed? Both the current docs and the patch
ignore this bug.
As with patch #2, this is primarily about reformatting/reorganizing.
Although it also adds the limitation from asm labels re statics.
I was hoping to modify the text to say that local register variables can
"only" be used to call Extended asm. This would greatly simplify this
section. But there has been pushback on this (despite the fact that no
one has really suggested any other reasonable use). So I have softened
this, and listed things from the existing docs that are explicitly not
supported.
For people who find the HTML easier to review:
Here's the current text:
https://gcc.gnu.org/onlinedocs/gcc/Local-Reg-Vars.html
And here's the new:
http://limegreensocks.com/gcc/Local-Register-Variables.html
dw
Index: extend.texi
===================================================================
--- extend.texi (revision 228690)
+++ extend.texi (working copy)
@@ -8604,7 +8604,7 @@
@cindex specifying registers for local variables
@cindex registers for local variables
-You can define a local register variable with a specified register
+You can define a local register variable and associate it with a specified register
like this:
@smallexample
@@ -8614,45 +8614,19 @@
@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.
+variables, but for a local variable the declaration appears within 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, 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 assembler
-instruction template part of an @code{asm} statement and assume it
-always refers to this variable.
-However, using the variable as an input or output operand to the @code{asm}
-guarantees that the specified register is used for that operand.
-@xref{Extended Asm}, for more information.
-
-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 intended 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{};
@@ -8661,11 +8635,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{};
@@ -8675,6 +8649,37 @@
asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
@end smallexample
+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. For this reason, the following uses
+are explicitly @emph{not} supported. If they appear to work, it is only
+happenstance, and may stop working as intended due to (seemingly)
+unrelated changes in surrounding code, or even minor changes in the
+optimization of a future version of gcc:
+
+@itemize @bullet
+@item Passing parameters to or from Basic @code{asm}, or passing parameters
+to or from Extended @code{asm} without using input or output operands.
+@item Passing parameters to or from routines written in assembler.
+@item Micro-optimizing code by manually specifying registers. While the
+generated code will still function correctly, any benefits from this type of
+micro-optimizing can vanish if the optimizers take even slightly different
+paths.
+@end itemize
+
+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.
+
+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.
+
+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}).
+
@node Size of an asm
@subsection Size of an @code{asm}
