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]

Proposed doc update for Explicit Reg Vars 3/3


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}
 

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