RE: [PATCH][MIPS] Documentation cleanup and typos

[Matthew Fortune <Matthew dot Fortune at imgtec dot com>]

Richard Sandiford <rdsandiford@googlemail.com>  writes:
> Matthew Fortune <Matthew.Fortune@imgtec.com> writes:
> >  @item
> >  3 for files using the software floating-point ABI.
> >  @item
> > -4 for files using the hardware floating-point ABI with 64-bit wide
> > -double-precision floating-point registers and 32-bit wide general
> > +4 for files using the deprecated hardware floating-point ABI which used
> 64-bit
> > +wide floating-point registers, 32-bit wide generation purpose registers
> and
> > +increased the number of callee-saved floating-point registers.
> 
> "general-purpose" rather than "generation purpose".  I think GCC style
> would be to use "64-bit-wide X" (or just "64-bit X") rather than
> "64-bit wide X", on the basis that without hyphens it could look like
> we're talking about wide Xs that have 64 bits.  Also...
> 
> > +@item
> > +5 for files using the hardware floating-point ABI with a double-precision
> FPU
> > +with either 32-bit or 64-bit floating-point registers and 32-bit general
> >  purpose registers.
> 
> ...this drops the "wide" thing and still reads naturally, so let's do
> that everywhere.

OK. The 'wide' did seem weird but I went with what was there as a first go.

> "general-purpose" here and later too.
> 
> > +@item
> > +6 for files using the hardware floating-point ABI with 64-bit wide
> > +floating-point registers and 32-bit wide general purpose registers.
> > +@item
> > +7 for files using the hardware floating-point ABI with 64-bit wide
> > +floating-point registers, 32-bit wide general purpose registers and
> forbids
> > +direct use of odd-numbered single-precision floating-point registers.
> 
> Maybe something like:
> 
> 7 for files using the hardware floating-point ABI with 64-bit floating-point
> registers, 32-bit general-purpose registers and a rule that forbids the
> direct ...
> 
> to avoid "with ... and forbids"?
> 
> OK with those changes, thanks.
> 
> > diff --git a/gas/doc/c-mips.texi b/gas/doc/c-mips.texi
> > index 8d61d04..d960022 100644
> > --- a/gas/doc/c-mips.texi
> > +++ b/gas/doc/c-mips.texi
> > @@ -769,9 +769,9 @@ The @code{.global} and @code{.globl} directives
> supported by
> >  region of data not code.  This means that, for example, any
> >  instructions following such a symbol will not be disassembled by
> >  @code{objdump} as it will regard them as data.  To change this
> > -behaviour an optional section name can be placed after the symbol name
> > +behavior an optional section name can be placed after the symbol name
> 
> ...even this one, though it makes me sad. :-)

Me too. I was trying to find some consistency and American spellings were
more prolific. There are still a few oddities if you look at the
documentation as a whole. I'll try and find time to do this same exercise
on the rest of the gas documentation.

> Maybe at some point it'd be worth turning the FP ABI list into a table,
> since the written-out version is getting pretty complex.

Agreed. I also have a way to simplify the hideously complex linkage rules
for attribute 4 and the warning messages that we spent some time trying
to improve. Bizarrely enough I found a nice representation while writing
qemu user-mode emulation for the new FP modes and described each ABI
extension in terms of the 5 'hardware' modes:

soft, single, fr0, fr1, fre

By creating a table to show which hardware mode(s) each FP ABI can be
executed in then the link rules become quite simple. 'and' together all
the modes and if there is still one left then the link is OK. For the
static link we do not allow an object to inherently require FRE mode
though so that wouldn't be needed in gas/ld.
I have used this approach in the latest incarnation of the GLIBC patch
for FPXX and I think the code is much cleaner for it.

I don't think I'll get round to a rework in binutils until I've got
through review of several gcc and glibc patches though.

Thanks,
Matthew