[RFA:] Improve "asm-reg in asm" documentation (was: Re: [m68k] asmregression with 3.3/3.4/3.5)

[Hans-Peter Nilsson <hp at bitrange dot com>]

(Sorry for sitting on this until now.  I tend to get behind on
lists, start a reply-message on an issue I see, then postpone
and wait until I get in sync before I send to make sure the
issue isn't moot, then forget about it for yet some time...)

On Wed, 12 May 2004, Ian Lance Taylor wrote:
> Richard Henderson <rth@redhat.com> writes:
>
> > On Wed, May 12, 2004 at 12:13:17PM -0400, Ian Lance Taylor wrote:
> > > In the asm statement, you said that the input _bn could be in any
> > > register.  You didn't say that it had to be in A6.
> >
> > Actually, he did -- he passed a hard register varible a6 to the asm.
> > GCC is supposed to *not* cse hard register variables from asms
> > specifically for this case -- making syscalls.
>
> Hmmm, this case is not documented as far as I can see--in the docs I
> don't see any special interaction between asm and local register
> variables.

IIRC I tried to improve this some time in the past, but it seems
I failed, because I don't find it reasonably clear myself now.
It is mentioned *in passing* in Extended Asm, and in Explicit
Reg Vars it seems to contradict itself.  Not to mention what it
says in Local Reg Vars.

How about this:

First hunk, @node{Extended Asm}.
Here, asmreg-in-asm *is* documented, but just in passing and that's not
enough to make its usefulness clear, QED.  The location of the clarification
doesn't give itself naturally; maybe it'd be better placed right after
the introduction of the constraints part of an asm, but then it'd refer to
things before not yet documented.  (BTW, I noticed there's a duplicate
named-operands blurb right before it.  I'll remove that as obvious because
the first copy is better placed.)

Second hunk, @node{Explicit Reg Vars}.
This passage doesn't *really* contradict the promised use of the specified
register in an asm statement, but methinks it's vague enough to enable
that interpretation.  I though better make the relation to asm statements
clear.

Third hunk, @node{Local Reg Vars}.
Here for the first time we explicitly Guarantee (there is no guarantee)
the intended register allocation, instead of being vague enough to serve
as a contradiction(!) when using the right (wrong) glasses.

Tested by "make dvi info".  The dvi output looks ok to me.

Ok to commit?
Any branches?  (The behavior is as documented since 2.7-ish modulo bugs.)

	* doc/extend.texi (Extended Asm): Add blurb about using Explicit
	Reg Vars to enforce register allocation with general constraints.
	(Explicit Reg Vars): Clarify relation to asm statements.
	(Local Reg Vars): Similar.

Index: extend.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/extend.texi,v
retrieving revision 1.215
diff -p -c -r1.215 extend.texi
*** extend.texi	10 Sep 2004 11:26:20 -0000	1.215
--- extend.texi	13 Sep 2004 04:45:08 -0000
*************** asm ("cmoveq %1,%2,%[result]"
*** 3560,3565 ****
--- 3561,3580 ----
       : "r" (test), "r"(new), "[result]"(old));
  @end smallexample

+ Sometimes you need to make an @code{asm} operand be a specific register,
+ but there's no matching constraint letter for that register @emph{by
+ itself}.  To force the operand into that register, use a local variable
+ for the operand and specify the register in the variable declaration.
+ @xref{Explicit Reg Vars}.  Then for the @code{asm} operand, use any
+ register constraint letter that matches the register:
+
+ @smallexample
+ register int *p1 asm ("r0") = @dots{};
+ register int *p2 asm ("r1") = @dots{};
+ register int *result asm ("r0");
+ asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+ @end smallexample
+
  Some instructions clobber specific hard registers.  To describe this,
  write a third colon after the input operands, followed by the names of
  the clobbered hard registers (given as strings).  Here is a realistic
*************** very often.
*** 3953,3959 ****

  @item
  Local register variables in specific registers do not reserve the
! registers.  The compiler's data flow analysis is capable of determining
  where the specified registers contain live values, and where they are
  available for other uses.  Stores into local register variables may be deleted
  when they appear to be dead according to dataflow analysis.  References
--- 3968,3976 ----

  @item
  Local register variables in specific registers do not reserve the
! registers, except at the point where they are used as input or output
! operands in an @code{asm} statement and the @code{asm} statement itself is
! not deleted.  The compiler's data flow analysis is capable of determining
  where the specified registers contain live values, and where they are
  available for other uses.  Stores into local register variables may be deleted
  when they appear to be dead according to dataflow analysis.  References
*************** the variable's value is not live.
*** 4102,4109 ****

  This option does not guarantee that GCC will generate code that has
  this variable in the register you specify at all times.  You may not
! code an explicit reference to this register in an @code{asm} statement
! and assume it will always refer to this variable.

  Stores into local register variables may be deleted when they appear to be dead
  according to dataflow analysis.  References to local register variables may
--- 4119,4129 ----

  This option does not guarantee that GCC will generate 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 @emph{assembler
! instruction template} part of an @code{asm} statement and assume it will
! always refer to this variable.  However, using the variable as an
! @code{asm} @emph{operand} guarantees that the specified register is used
! for the operand.

  Stores into local register variables may be deleted when they appear to be dead
  according to dataflow analysis.  References to local register variables may

brgds, H-P