[PATCH] doc: discourage const/volatile on register variables

[Alexander Monakov]

Hi,

when using explicit register variables ('register int foo asm("%ebp");'),
using const/volatile type qualifiers on the declaration does not result in
the logically expected effect.

The main issue is that gcc-8 got "better" at propagating initializers of
'register const' variables to their uses in asm operands, losing the
association with the register and thus causing the operand to
unexpectedly appear in some other register. This caused build issues for
the Linux kernel and was reported a couple of times in the GCC Bugzilla.

This patch adds a few lines to the documentation to say that qualifiers
won't work as expected. OK for trunk?

Thanks.
Alexander

	PR target/86673
	doc/extend.texi (Global Register Variables): Discourage use of type
	qualifiers.
	(Local Register Variables): Likewise.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 7b471ec40f7..9a41f2753e9 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -9591,6 +9591,11 @@ a global variable the declaration appears outside a function. The
 @code{static}. The register name must be a valid register name for the
 target platform.
 
+Do not use type qualifiers such as @code{const} and @code{volatile}, as
+the result may be contrary to your expectations. In  particular, using
+the @code{volatile} qualifier does not fully prevent the compiler from
+optimizing accesses to the register.
+
 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.
@@ -9698,6 +9703,12 @@ but for a local variable the declaration appears within a function.  The
 @code{static}.  The register name must be a valid register name for the
 target platform.
 
+Do not use type qualifiers such as @code{const} and @code{volatile}, as
+the result may be contrary to your expectations. In particular, when
+the @code{const} qualifier is used, the compiler may substitute the
+variable with its initializer in @code{asm} statements, which may cause
+the corresponding operand to appear in a different register.
+
 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 calls to library routines will not clobber it.