This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [PATCH] MIPS: IEEE 754-2008 NaN encoding features


"Maciej W. Rozycki" <macro@codesourcery.com> writes:
>  * MIPS assembly options:: Directives to control code generation
>  * MIPS autoextend::	Directives for extending MIPS 16 bit instructions
>  * MIPS insn::		Directive to mark data as an instruction
> +* MIPS nan::		Directives to mark IEEE 754 NaN data encoding
>  * MIPS Option Stack::	Directives to save and restore options
>  * MIPS ASE Instruction Generation Overrides:: Directives to control
>    			generation of MIPS ASE instructions

Please use:

MIPS NaN Encodings::	Directives to record which NaN encoding is being used

Yes, the doc cleanups are still WIP...

> +  /* Compare NaN encodings.  */
> +  if ((new_flags & EF_MIPS_NAN2008) != (old_flags & EF_MIPS_NAN2008))
> +    {
> +      _bfd_error_handler (_("%B: linking %s module with previous %s modules"),
> +			  ibfd,
> +			  (new_flags & EF_MIPS_NAN2008
> +			   ? "2008 NaN" : "legacy NaN"),
> +			  (old_flags & EF_MIPS_NAN2008
> +			   ? "2008 NaN" : "legacy NaN"));

For translation, I think this should be:

      _bfd_error_handler (_("%B: linking %s-NaN module with previous %s-NaN modules"),
			  ibfd,
			  new_flags & EF_MIPS_NAN2008 ? "2008" : "legacy",
			  old_flags & EF_MIPS_NAN2008 ? "2008" : "legacy");

or:

      _bfd_error_handler (_("%B: linking %s module with previous %s modules"),
			  ibfd,
			  (new_flags & EF_MIPS_NAN2008
			   ? "-mnan=2008" : "-mnan=legacy"),
			  (old_flags & EF_MIPS_NAN2008
			   ? "-mnan=2008" : "-mnan=legacy"));

etc.  I'd prefer the latter FWIW.  Even though it's possible to have a
link in which ".nan" was used and "-mnan" never was, I think in practice
the command-line option will have been involved somewhere, and quoting
commnd-line options seems more user-friendly.

> @@ -416,6 +417,48 @@ Also no MIPS16 branches are ever relaxed
>  By default @samp{--no-relax-branch} is selected, causing any out-of-range
>  branches to produce an error.
>  
> +@cindex @option{-mnan=@var{encoding}} command line option, MIPS
> +@item -mnan=@var{encoding}
> +This options controls the encoding of the special not-a-number (NaN)
> +IEEE 754 floating-point symbolic data.
> +
> +By default @option{-mnan=legacy} or the legacy encoding is selected.  In
> +this case quiet NaNs (qNaNs) are denoted by the first bit of their
> +trailing significand field being 0, whereas signalling NaNs (sNaNs) are
> +denoted by the first bit of their trailing significand field being 1.
> +
> +The @option{-mnan=2008} option selects the IEEE 754-2008 encoding.  In
> +this case qNaNs are denoted by the first bit of their trailing significand
> +field being 1, whereas sNaNs are denoted by the first bit of their
> +trailing significand field being 0.
> +
> +@sc{gnu} @code{@value{AS}} does not produce NaNs itself and therefore this
> +option does not affect code generated.  Instead it is used, in combination
> +with the @code{.nan} directive (@pxref{MIPS nan}), to control link-time
> +compatibility of ELF object files, by setting the @code{NAN2008} ELF file
> +header flag as appropriate.
> +
> +In the absence of a @code{.nan} directive to set the @code{NAN2008} ELF
> +file header flag in a file being assembled the option is processed as
> +follows:
> +
> +@itemize @bullet
> +@item
> +for maximum backwards compatibility, by default or in the presence of
> +the @option{-mnan=legacy} option the @code{NAN2008} ELF file header flag
> +is cleared, marking the object file compatible with objects that use the
> +legacy NaN encoding,
> +@item
> +in the presence of the @option{-mnan=2008} option the @code{NAN2008} ELF
> +file header flag is set, marking the object file compatible with objects
> +that use the IEEE 754-2008 NaN encoding.
> +@end itemize
> +
> +In the presence of a @code{.nan} directive to set the @code{NAN2008} ELF
> +file header flag a file being assembled, the effective (last) value
> +requested with the directive overrides any setting requested with the
> +@option{-mnan=@var{encoding}} option.

Let's make this a bit shorter, something like:

--------------------------------------------------------------------------
This option indicates whether the source code uses the IEEE 2008
NaN encoding (@option{-mnan=2008}) or the original MIPS encoding
(@option{-mnan=legacy}).  It is equivalent to adding a @code{.nan}
directive to the beginning of the source file.  @xref{MIPS NaN Encodings}.

@option{-mnan=legacy} is the default if no @option{-mnan} option or
@code{.nan} directive is used.
--------------------------------------------------------------------------

> +@cindex MIPS IEEE 754 NaN data encoding selection
> +@kindex @code{.nan legacy}
> +@kindex @code{.nan 2008}
> +These directives control the encoding of the special not-a-number (NaN)
> +IEEE 754 floating-point symbolic data.

IMO "values" reads better than "symbolic data".  (IEEE754 itself refers
to them as "values".)

But we can't really start the section like this, because the @kindex
lines only insert index entries.  Nothing appears inline.  I'd suggest:

--------------------------------------------------------------------------
The IEEE 754 floating-point standard defines two types of not-a-number
(NaN) value: ``signalling'' NaNs and ``quiet'' NaNs.  The original
version of the standard did not specify how these two types should be
distinguished.  Most implementations followed the i387 model, in which
the first bit of the significand is set for quiet NaNs and clear for
signalling NaNs.  However, the original MIPS implementation assigned the
opposite meaning to the bit, so that it was set for signalling NaNs and
clear for quiet NaNs.

The 2008 revision of the standard formally suggested the i387 choice
and an uncoming release of the MIPS architecture will therefore support
that form.  Code that uses one NaN encoding would usually be incompatible
with code that uses the other NaN encoding, so MIPS ELF objects have a flag
(@code{EF_MIPS_NAN2008}) to record which encoding is being used.

Assembly files can use the @code{.nan} directive to select between the
two encodings.  @samp{.nan 2008} says that the assembly file uses the
IEEE 754-2008 encoding while @samp{.nan legacy} says that the file uses
the original MIPS encoding.  If several @code{.nan} directives are given,
the final setting is the one that is used.

The command-line options @option{-mnan=legacy} and @option{-mnan=2008}
can be used instead of @samp{.nan 2008} and @samp{.nan legacy} respectively.
However, any @code{.nan} directive overrides the command-line setting.

@samp{.nan legacy} is the default if no @code{.nan} directive or
@option{-mnan} option is given.

Note that @sc{gnu} @code{@value{AS}} does not produce NaNs itself and therefore
these directives do not affect code generation.  They simply control the
setting of the @code{EF_MIPS_NAN2008} flag.
--------------------------------------------------------------------------

...which I'm sure needs some copy-editing and tweaking.

Looks good otherwise, thanks.  OK with those changes if you're happy with
them, otherwise let me know.

Richard


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]