Re: [patch] extend.texi MIPS PS/3D Support

[Richard Sandiford <rsandifo at redhat dot com>]

This is awesome.  Thanks a lot for doing this.

Some very minor niggles:

"Fu, Chao-Ying" <fu@mips.com> writes:
> + * MIPS Paired-Single Floating Point Instruction Support::

Maybe drop "Instruction"?

> + @menu
> + * Built-in Functions for MIPS64 Paired-Single Instructions::
> + * Built-in Functions for MIPS-3D ASE Instructions::
> + @end menu

I'm not sure how canonical it is to have the section start with a menu
and be followed by a lengthy (but very good!) overview.  It might well
be OK, but maybe a docs maintainer can comment.

Perhaps a lot of the overview could go in a subsection of its own,
alongside the two nodes above.

> + The MIPS64 Architecture includes a number of paired-single floating point (FP) 
> + instructions.  These paired-single instructions operate on
> + 64-bit floating point registers containing two single floating point values
> + each in two contiguous 32-bits of the register, that is, one in the upper
> + half and one in the lower half.  This type of vector representation of two 
> + single FP values can then be operated upon simultaneously by a single 
> + instruction in a SIMD (single instruction multiple data) fashion, also called 
> + paired-single instructions in the MIPS sentence.  GCC supports the 
                                  ^^^^^^^^^^^^^^^^^
I think you mean "MIPS terminology", or something like that.  Although
everything after "also called..." is a little redundant since you've
already introduced the term "paired-single instructions".

> + To enable paired-single instruction support, the command line option 
> + @option{-mpaired-single} must be used.  Also, the hardware floating point 
> + option @option{-mhard-float} and the 64-bit FP register option 
> + @option{-mfp64} must be turned on either by default or by explicit command 
> + line options.
> + 
> + @smallexample
> + gcc -mips64 -mpaired-single -c hello.c
> + gcc -mips64 -mpaired-single -mhard-float -mfp64 -c hello.c
> + @end smallexample
> + 
> + To use paired-single variables in C, the following @code{typedef} is
> + required.
> + @smallexample
> + typedef float v2sf __attribute__ ((vector_size (8)));
> + @end smallexample
> + 
> + This @code{typedef} defines @code{v2sf} as an 8-byte data type which base type 
> + is @code{float} (4 bytes), so a @code{v2sf} variable contains two 
> + @code{float}s in a SIMD fashion.
> + 
> + The following illustrates by example, how SIMD variables can be declared,
> + initialized, and used in a C program.  Note that declaring and using SIMD 
> + variables in this way allows the compiler to use the appropriate SIMD 
> + instructions without any explicit direction from the user.
> + 
> + @table @asis
> + @item Variable Declaration
> + @smallexample
> + v2sf a, b, c, d;
> + /* @r{This declares four variables a, b, c, and d as a paired-single data type.}  */

I suspect that this should reall be "@code{a}, @code{b}, ...".

> + @end smallexample
> + 
> + @item Variable Initialization
> + @smallexample
> + v2sf a = @{1.5, 9.1@};
> + v2sf b;
> + float e, f;
> + b = (v2sf) @{e, f@};
> + @end smallexample
> + 
> + NOTE: The CPU endianness determines how paired-single variables are initialized,

I think this should be @emph{Note:}.

> + i.e., which value goes into the upper and which goes into the lower part
> + of the paired-single floating point register.
> + For little-endian CPUs, the first single value goes into the lower part,
> + and the second single value goes into the upper part.  For example,
> + @code{v2sf a = @{1.5, 9.1@};}, @code{1.5} goes into the lower part and 
> + @code{9.1} goes into the upper part.

How about:

    For example, @code{v2sf a = @{1.5, 9.1@};} will put @code{1.5} into
    the lower part and @code{9.1} into the upper part.

> + The examples below illustrate the usage of the declared SIMD data type 
> + variables that allow the compiler to automatically invoke paired-single
> + instructions.  The instruction invoked in each case is shown in parentheses.

The first sentence doesn't sound quite right, but I can't think of
anything better right now.

> + 
> + @table @asis
> + @item Assignment (MOV.PS)

Maybe better to use "(@code{mov.ps})", here and elsewhere?

> + @item Conditional Move Based on Integer Comparison (MOVN.PS, MOVZ.PS)
> + @smallexample
> + int i, j;
> + v2sf a, b, c;
> + a = (i > j) ? b : c;
> + /* Or */
> + if (i > j)
> +   a = b;
> + else
> +   a = c;
> + @end smallexample
> + @end table

Apparently that should be "@r{Or}".  So many things to remember... ;)

> + @node Built-in Functions for MIPS64 Paired-Single Instructions
> + @subsubsection Built-in Functions for MIPS64 Paired-Single Instructions 
> + 
> + Built-in functions invoke explicit SIMD instructions by the user in C.

Maybe something like "Built-in functions can be used to explicitly
invoke a particular SIMD instruction"?

> + They are used in situations when merging paired-single variables,
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^
Suggest "to merge" (with rest of sentence changing accordingly).

> + NOTE: The value of the third parameter @code{int} must be 0 or 4 

Another @emph{Note:}.

> + @item v2sf __builtin_mips_mov*_c_*_ps (v2sf, v2sf, v2sf, v2sf)
> + Conditional move based on floating point comparison (C.*.PS, MOVT.PS/MOVF.PS).
> + 
> + The first * = @code{t}, @code{f}
> + 
> + The second * = @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, 
> + @code{ult}, @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 
> + @code{ngl}, @code{lt}, @code{nge}, @code{le}, @code{ngt}

Probably better to use @var{...} instead of "*" here.  E.g.:

__builtin_mips_mov@var{tf}_c_@var{cond}_ps

Richard