[1/2] extend.texi: update Global Register Variables section

Message ID 20180423175348.26101-2-amonakov@ispras.ru
State New
Headers show
Series
  • Require that constraints are used to reference global regs
Related show

Commit Message

Alexander Monakov April 23, 2018, 5:53 p.m.
This rewrites global register vars doc to reflect that the register is no longer
reserved exclusively, but in fact is available for general allocation, and also
adds the requirement to properly inform the compiler where inline asms are
accessing the variable.

This:
-@item The register is not saved and restored by any functions.
is reworded to verbosely spell out gotchas related to calls/returns.

	* extend.texi (Global Register Variables): Rewrite the bullet list.
	Note that the register is available for allocation. Note that access
	via inline asm must use constraints. Add note about async-signal
	handlers. Remove paragraph about automagic register selection.
---
 gcc/doc/extend.texi | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

-- 
2.13.3

Comments

Alexander Monakov May 10, 2018, 9:47 a.m. | #1
On Mon, 23 Apr 2018, Alexander Monakov wrote:

> This rewrites global register vars doc to reflect that the register is no longer

> reserved exclusively, but in fact is available for general allocation, and also

> adds the requirement to properly inform the compiler where inline asms are

> accessing the variable.

> 

> This:

> -@item The register is not saved and restored by any functions.

> is reworded to verbosely spell out gotchas related to calls/returns.

> 

> 	* extend.texi (Global Register Variables): Rewrite the bullet list.

> 	Note that the register is available for allocation. Note that access

> 	via inline asm must use constraints. Add note about async-signal

> 	handlers. Remove paragraph about automagic register selection.

> ---

>  gcc/doc/extend.texi | 29 +++++++++++++++++++----------

>  1 file changed, 19 insertions(+), 10 deletions(-)


Ping? I believe the substance of new text has been hashed out with Michael.
I'd appreciate a review for language and style issues.

Thanks.
Alexander

> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi

> index 5571d05d93b..f663741e36c 100644

> --- a/gcc/doc/extend.texi

> +++ b/gcc/doc/extend.texi

> @@ -9549,11 +9549,21 @@ After defining a global register variable, for the current compilation

>  unit:

>  

>  @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.

> +@item If the register is a call-saved register, call ABI is affected:

> +the register will not be restored in function epilogue sequences after

> +the variable has been assigned.  Therefore, functions cannot safely

> +return to callers that assume standard ABI.

> +@item Conversely, if the register is a call-clobbered register, making

> +calls to functions that use standard ABI may lose contents of the variable.

> +Such calls may be created by the compiler even if none are evident in

> +the original program, for example when libgcc functions are used to

> +make up for unavailable instructions.

> +@item Accesses to the variable may be optimized as usual and the register

> +remains available for allocation and use in any computations, provided that

> +observable values of the variable are not affected.

> +@item If the variable is referenced in inline assembly, the type of access

> +must be provided to the compiler via constraints (@pxref{Constraints}).

> +Accesses from basic asms are not supported.

>  @end itemize

>  

>  Note that these points @emph{only} apply to code that is compiled with the

> @@ -9595,7 +9605,10 @@ 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.

> +temporarily use the register for other things.  Furthermore, since the register

> +is not reserved exclusively for the variable, accessing it from handlers of

> +asynchronous signals may observe unrelated temporary values residing in the

> +register.

>  

>  @cindex register variable after @code{longjmp}

>  @cindex global register after @code{longjmp}

> @@ -9610,10 +9623,6 @@ 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

>  thing happens regardless of what @code{longjmp} does.

>  

> -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.

> -

>  @node Local Register Variables

>  @subsubsection Specifying Registers for Local Variables

>  @anchor{Local Reg Vars}

>
Jeff Law May 21, 2018, 9:10 p.m. | #2
On 05/10/2018 03:47 AM, Alexander Monakov wrote:
> 

> 

> On Mon, 23 Apr 2018, Alexander Monakov wrote:

> 

>> This rewrites global register vars doc to reflect that the register is no longer

>> reserved exclusively, but in fact is available for general allocation, and also

>> adds the requirement to properly inform the compiler where inline asms are

>> accessing the variable.

>>

>> This:

>> -@item The register is not saved and restored by any functions.

>> is reworded to verbosely spell out gotchas related to calls/returns.

>>

>> 	* extend.texi (Global Register Variables): Rewrite the bullet list.

>> 	Note that the register is available for allocation. Note that access

>> 	via inline asm must use constraints. Add note about async-signal

>> 	handlers. Remove paragraph about automagic register selection.

>> ---

>>  gcc/doc/extend.texi | 29 +++++++++++++++++++----------

>>  1 file changed, 19 insertions(+), 10 deletions(-)

> 

> Ping? I believe the substance of new text has been hashed out with Michael.

> I'd appreciate a review for language and style issues.

> 

> Thanks.

> Alexander

> 

>> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi

>> index 5571d05d93b..f663741e36c 100644

>> --- a/gcc/doc/extend.texi

>> +++ b/gcc/doc/extend.texi

>> @@ -9549,11 +9549,21 @@ After defining a global register variable, for the current compilation

>>  unit:

>>  

>>  @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.

>> +@item If the register is a call-saved register, call ABI is affected:

>> +the register will not be restored in function epilogue sequences after

>> +the variable has been assigned.  Therefore, functions cannot safely

>> +return to callers that assume standard ABI.

Whether or not a global register is saved in the prologue and restored
in the epilogue is actually a function of the target's prologue/epilogue
implementation.

So ISTM this paragraph needs to be refined a bit.  Essentially it may or
may not change the ABI.  It really depends on the target implementation.


The rest of the doc changes look fine.

jeff
Alexander Monakov May 22, 2018, 4:44 a.m. | #3
On Mon, 21 May 2018, Jeff Law wrote:
> Whether or not a global register is saved in the prologue and restored

> in the epilogue is actually a function of the target's prologue/epilogue

> implementation.

> 

> So ISTM this paragraph needs to be refined a bit.  Essentially it may or

> may not change the ABI.  It really depends on the target implementation.


As far as I can tell, that would be a target bug; if global registers are
restored in epilogues, they are not useful.

Alexander

Patch

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 5571d05d93b..f663741e36c 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9549,11 +9549,21 @@  After defining a global register variable, for the current compilation
 unit:
 
 @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.
+@item If the register is a call-saved register, call ABI is affected:
+the register will not be restored in function epilogue sequences after
+the variable has been assigned.  Therefore, functions cannot safely
+return to callers that assume standard ABI.
+@item Conversely, if the register is a call-clobbered register, making
+calls to functions that use standard ABI may lose contents of the variable.
+Such calls may be created by the compiler even if none are evident in
+the original program, for example when libgcc functions are used to
+make up for unavailable instructions.
+@item Accesses to the variable may be optimized as usual and the register
+remains available for allocation and use in any computations, provided that
+observable values of the variable are not affected.
+@item If the variable is referenced in inline assembly, the type of access
+must be provided to the compiler via constraints (@pxref{Constraints}).
+Accesses from basic asms are not supported.
 @end itemize
 
 Note that these points @emph{only} apply to code that is compiled with the
@@ -9595,7 +9605,10 @@  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.
+temporarily use the register for other things.  Furthermore, since the register
+is not reserved exclusively for the variable, accessing it from handlers of
+asynchronous signals may observe unrelated temporary values residing in the
+register.
 
 @cindex register variable after @code{longjmp}
 @cindex global register after @code{longjmp}
@@ -9610,10 +9623,6 @@  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
 thing happens regardless of what @code{longjmp} does.
 
-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.
-
 @node Local Register Variables
 @subsubsection Specifying Registers for Local Variables
 @anchor{Local Reg Vars}