[rs6000] Add documentation for __builtin_mtfsf

[rs6000] Add documentation for __builtin_mtfsf

[Paul Clarke]

2019-07-21  Paul A. Clarke  <pc@us.ibm.com>

[gcc]

	* doc/extend.texi: Add documentation for __builtin_mtfsf.

Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 273615)
+++ gcc/doc/extend.texi	(working copy)
@@ -16848,6 +16848,7 @@ unsigned long __builtin_ppc_mftb ();
 double __builtin_unpack_ibm128 (__ibm128, int);
 __ibm128 __builtin_pack_ibm128 (double, double);
 double __builtin_mffs (void);
+double __builtin_mtfsf (const int, double);
 void __builtin_mtfsb0 (const int);
 void __builtin_mtfsb1 (const int);
 void __builtin_set_fpscr_rn (int);
@@ -16864,6 +16865,10 @@ return the value of the FPSCR register.  Note, ISA
 @code{__builtin_mffsl()} which permits software to read the control and
 non-sticky status bits in the FSPCR without the higher latency associated with
 accessing the sticky status bits.  The
+@code{__builtin_mtfsf} takes a constant 8-bit integer field mask and a
+representation of the new value of the FPSCR and generates the @code{mtfsf}
+instruction to copy the supplied value into the FPSCR, subject to the field
+mask, each bit of which represents a nibble of the FPSCR.  The
 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
 as an argument.  The valid bit range is between 0 and 31.  The builtins map to
 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and

--
PC

Re: [rs6000] Add documentation for __builtin_mtfsf

[Segher Boessenkool]

Hi Paul,

On Sun, Jul 21, 2019 at 04:06:32AM -0500, Paul Clarke wrote:
> @@ -16864,6 +16865,10 @@ return the value of the FPSCR register.  Note, ISA
>  @code{__builtin_mffsl()} which permits software to read the control and
>  non-sticky status bits in the FSPCR without the higher latency associated with
>  accessing the sticky status bits.  The
> +@code{__builtin_mtfsf} takes a constant 8-bit integer field mask and a
> +representation of the new value of the FPSCR and generates the @code{mtfsf}
> +instruction to copy the supplied value into the FPSCR, subject to the field
> +mask, each bit of which represents a nibble of the FPSCR.  The
>  @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change
>  as an argument.  The valid bit range is between 0 and 31.  The builtins map to
>  the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and

"A representation of the new value"?  I guess you want to say that it
sits in an FPR?

Before we document __builtin_mtfsf, maybe we should make it work with
the W and/or L fields first, or at least, decide how we want that?


Segher

Re: [rs6000] Add documentation for __builtin_mtfsf

[Paul Clarke]

On 7/21/19 1:13 PM, Segher Boessenkool wrote:
> On Sun, Jul 21, 2019 at 04:06:32AM -0500, Paul Clarke wrote:
>> +@code{__builtin_mtfsf} takes a constant 8-bit integer field mask and a
>> +representation of the new value of the FPSCR and generates the @code{mtfsf}
>> +instruction to copy the supplied value into the FPSCR, subject to the field
>> +mask, each bit of which represents a nibble of the FPSCR.  The

> "A representation of the new value"?  I guess you want to say that it
> sits in an FPR?

It's the 2nd parameter to the builtin, so a "double".  It may or may not be in an FPR, but the user of the builtin doesn't really know or care.  (It'll eventually be in an FPR, of course, but the user has it in a variable.)  It's a "representation" because it's not actually the new value, because it gets written under mask.

> Before we document __builtin_mtfsf, maybe we should make it work with
> the W and/or L fields first, or at least, decide how we want that?

It's been available but undocumented for ages.  Do you want me to thus document how it is currently implemented by including something like "...generates the mtfsf (extended mnemonic) instruction ..." ?

If you think the basic mnemonic form needs to be supported, that's a whole other piece of work ;-)

PC

Re: [rs6000] Add documentation for __builtin_mtfsf

[Segher Boessenkool]

On Sun, Jul 21, 2019 at 02:50:41PM -0500, Paul Clarke wrote:
> On 7/21/19 1:13 PM, Segher Boessenkool wrote:
> > On Sun, Jul 21, 2019 at 04:06:32AM -0500, Paul Clarke wrote:
> >> +@code{__builtin_mtfsf} takes a constant 8-bit integer field mask and a
> >> +representation of the new value of the FPSCR and generates the @code{mtfsf}
> >> +instruction to copy the supplied value into the FPSCR, subject to the field
> >> +mask, each bit of which represents a nibble of the FPSCR.  The

("nybble" fwiw.  Well the spelling list wisely avoids this one, so maybe
so should we ;-) )

> > "A representation of the new value"?  I guess you want to say that it
> > sits in an FPR?
> 
> It's the 2nd parameter to the builtin, so a "double".

Yeah, it's an integer that sits in the low bits of a double.  It's
probably best to not even try to describe it, just refer to the machine
instruction?

> It may or may not be in an FPR, but the user of the builtin doesn't
> really know or care.  (It'll eventually be in an FPR, of course, but
> the user has it in a variable.)  It's a "representation" because it's
> not actually the new value, because it gets written under mask.

> > Before we document __builtin_mtfsf, maybe we should make it work with
> > the W and/or L fields first, or at least, decide how we want that?
> 
> It's been available but undocumented for ages.  Do you want me to thus
> document how it is currently implemented by including something like
> "...generates the mtfsf (extended mnemonic) instruction ..." ?

That's a good idea yes.  L=W=0.

> If you think the basic mnemonic form needs to be supported, that's a
> whole other piece of work ;-)

Sure :-)  My thinking was, if it wasn't documented and we want to
define new variants, we may have a bit more leeway.  But since this
is such and old builtin, that's not going to happen anyway.

So can you reword a little bit and resend please?  It really doesn't
need to say more than "this does what the mtfsf insn does", and saying
more is Hard :-)

Thanks,


Segher