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

[Gunther Nikl <gni at gecko dot de>]

On Mon, Sep 13, 2004 at 01:01:38AM -0400, Hans-Peter Nilsson wrote:
> (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...)

  You are doing it now.

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

  After I was told, that my expectations were wrong and I re-read the
  documentation. Indeed it wasn't clear on this issue and my usage of
  local register variables and extended asm could be viewed as wrong
  according the docs.

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

  This is exactly what m68k-amigaos does. There is still something that
  might need an explanation: the choosen register for p1 might be scratch
  register and assigned value to p2 might come from a function call. Could
  that cause probelms? Currently it doesn't but then m68k-amigaos uses a
  two-stage approach: first all arguments to the register vars are assigned
  to local vars which then are used as inputs to the register vars. I suppose
  this was done to help GCC.

>   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

  Thank you for writing this clarification. Hopefully, it describes what
  really is supposed to happen.

  Gunther