[RFC] User-visible changes for powerpc64-le-linux ABI changes

[Thomas Koenig <tkoenig@netcologne.de>]

Hi,

I have put together a summary of what users should see
as a change.  I've made this a diff against the current
documentation.  This is an RFC, please feel free to
suggest any changes.

I have put in a few remarks among the diff.

If there is general agreement that this is the best way forward, then
we can proceed along those lines.

Best regards

	Thomas

iff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index a54153b0951..89319a7836f 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -604,7 +604,7 @@ Malformed environment variables are silently ignored.
  * GFORTRAN_SHOW_LOCUS::  Show location for runtime errors
  * GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
  * GFORTRAN_LIST_SEPARATOR::  Separator for list output
-* GFORTRAN_CONVERT_UNIT::  Set endianness for unformatted I/O
+* GFORTRAN_CONVERT_UNIT::  Set conversion for unformatted I/O
  * GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
  * GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files
  * GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files
@@ -701,18 +701,25 @@ when @command{a.out} is the compiled Fortran 
program that you want to run.
  Default is a single space.

  @node GFORTRAN_CONVERT_UNIT
-@section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O
+@section @env{GFORTRAN_CONVERT_UNIT}---Set conversion for unformatted I/O

  By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible
  to change the representation of data for unformatted files.
-The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
+The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable for
+systems is:
  @smallexample
  GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
-mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
+mode: 'native' | 'swap' | 'big_endian' | 'little_endian' | power_mode;
+power_mode: 'r16_ieee' | 'native+r16_ieee' | 'swap+r16_ieee'
+            | 'big_endian+r16_ieee' | 'little_endian+r16_ieee'
+            | 'r16_ibm' | 'native+r16_ibm' | 'swap+r16_ibm'
+            | 'big_endian+r16_ibm' | 'little_endian+r16_ibm'
  exception: mode ':' unit_list | unit_list ;
-unit_list: unit_spec | unit_list unit_spec ;
+unit_list: unit_spec | unit_list ',' unit_spec ;
  unit_spec: INTEGER | INTEGER '-' INTEGER ;
  @end smallexample
+where @code{power_mode} is valid on POWER systems only.
+
  The variable consists of an optional default mode, followed by
  a list of optional exceptions, which are separated by semicolons
  from the preceding default and each other.  Each exception consists
@@ -726,6 +733,44 @@ the modes are the same as for the @code{CONVERT} 
specifier:
  for unformatted files.
  @item @code{BIG_ENDIAN} Use the big-endian format for unformatted files.
  @end itemize
+
+For POWER systems, additionally the options
+@itemize @w{}
+@item @code{R16_IEEE} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{NATIVE+R16_IEEE} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{SWAP+R16_IEEE} Swap between little- and big-endian,
+use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{LITTLE_ENDIAN+R16_IEEE} Use the little-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{BIG_ENDIAN+R16_IEEE} Use the big-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{R16_IEEE} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{NATIVE+R16_IEEE} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{SWAP+R16_IEEE} Swap between little- and big-endian,
+use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{LITTLE_ENDIAN+R16_IEEE} Use the little-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{BIG_ENDIAN+R16_IEEE} Use the big-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{R16_IBM} Use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{NATIVE+R16_IBM} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{SWAP+R16_IBM} Swap between little- and big-endian,
+use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{LITTLE_ENDIAN+R16_IBM} Use the little-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{BIG_ENDIAN+R16_IBM} Use the big-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{R16_IBM} Use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{NATIVE+R16_IBM} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{SWAP+R16_IBM} Swap between little- and big-endian,
+use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{LITTLE_ENDIAN+R16_IBM} Use the little-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{BIG_ENDIAN+R16_IBM} Use the big-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@end itemize
+are valid.
+

Remark: Not really sure if this is the most elegant way of putting
it, suggestions for improved wording welcome (but can be done later,
as long as the specification is not changed).


  A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
  Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
  @itemize @w{}
@@ -2141,6 +2186,44 @@ for unformatted files.
  unformatted files.
  @end itemize

+For POWER systems, there is also the possibility to convert between
+the ``IBM'' and the ``IEEE'' format for @code{REAL(KIND=16)}.  Additional
+valid values for @code{CONVERT} are:
+@itemize @w{}
+@item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='NATIVE+R16_IEEE'} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='SWAP+R16_IEEE'} Swap between little- and big-endian,
+use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='LITTLE_ENDIAN+R16_IEEE'} Use the little-endian 
format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='BIG_ENDIAN+R16_IEEE'} Use the big-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='NATIVE+R16_IEEE'} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='SWAP+R16_IEEE'} Swap between little- and big-endian,
+use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='LITTLE_ENDIAN+R16_IEEE'} Use the little-endian 
format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='BIG_ENDIAN+R16_IEEE'} Use the big-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='R16_IBM'} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='NATIVE+R16_IBM'} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='SWAP+R16_IBM'} Swap between little- and big-endian,
+use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='LITTLE_ENDIAN+R16_IBM'} Use the little-endian 
format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='BIG_ENDIAN+R16_IBM'} Use the big-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='R16_IBM'} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='NATIVE+R16_IBM'} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{CONVERT='SWAP+R16_IBM'} Swap between little- and big-endian,
+use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='LITTLE_ENDIAN+R16_IBM'} Use the little-endian 
format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{CONVERT='BIG_ENDIAN+R16_IBM'} Use the big-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@end itemize
+
  Using the option could look like this:
  @smallexample
    open(file='big.dat',form='unformatted',access='sequential', &
diff --git a/gcc/fortran/invoke.texi b/gcc/fortran/invoke.texi
index 0fb7e1add7e..82ca3eac522 100644
--- a/gcc/fortran/invoke.texi
+++ b/gcc/fortran/invoke.texi
@@ -127,7 +127,8 @@ by type.  Explanations are in the following sections.
  -fimplicit-none -finteger-4-integer-8 -fmax-identifier-length @gol
  -fmodule-private -ffixed-form -fno-range-check -fopenacc -fopenmp @gol
  -freal-4-real-10 -freal-4-real-16 -freal-4-real-8 -freal-8-real-10 @gol
--freal-8-real-16 -freal-8-real-4 -std=@var{std} -ftest-forall-temp
+-freal-8-real-16 -freal-8-real-4 -std=@var{std} -ftest-forall-temp @gol
+-freal-16=ibm -freal-16=ieee
  }


Remark: I am not sure if there will be an equivalent flag for C or C++.
If there is, we could make this an alias, or use the C/C++ flag instead
of a Fortran-specific one.

We will have to have some way of compiling the REAL(KIND=16) library
functions twice with the appropriate flag and also some additional
name mangling, for which a little bit of m4 hackery will be needed.


  @item Preprocessing Options
@@ -539,6 +540,34 @@ when passing a value to the @code{kind=} dummy 
argument.  Inspection of the
  intermediate representation of the translated Fortran code, produced by
  @option{-fdump-fortran-original} or @option{-fdump-tree-original}, is 
suggested.

+@item -freal-16=ibm
+@item -freal-16=ieee
+@opindex @code{freal-16=ibm}
+@opindex @code{freal-16=ieee}
+These options are only available on POWER systems.  They select
+between the two possible formats available on POWER systems for
+@code{REAL(KIND=16)} variables.  The ``IBM'' format consists of two
+doubles (also known as @code{double double} or @code{__ibm128} and
+the ``IEEE'' format of a 16-byte number in the format specified by
+``IEEE 754'' (also known as @code{__ieee128}).
+
+The default is @code{-freal-16=ibm}.
+
+These options change the ABI of the code.  Code containing
+@code{REAL=16} values compiled with one of these options is
+@emph{incompatible} with code compiled with the other option.  The
+compiler might or might not detect such incompatibilites, or they
+might lead to silent data corruption.
+
+In gfortran 11 or earlier, only the ``IBM'' format of
+@code{REAL(KIND=16)} was supported.
+
+The @ref{CONVERT specifier} can be used to read or write data
+unformatted data containing @code{REAL(KIND=16)} in either the ``IBM''
+or ``IEEE'' format, as can the @ref{GFORTRAN_CONVERT_UNIT} environment
+variable and the @option{-fconvert} option.
+
+
  @item -std=@var{std}
  @opindex @code{std=}@var{std} option
  Specify the standard to which the program is expected to conform,
@@ -1404,6 +1433,42 @@ swap between big- and little-endian; 
@samp{big-endian}, use big-endian
  representation for unformatted files; @samp{little-endian}, use 
little-endian
  representation for unformatted files.

+For POWER systems, there are additional options which specify if the
+``IEEE'' or the ``IBM'' format are used for @code{REAL(KIND=16)} variables
+for unformatted I/O.  Valid are:
+@item @code{r16-ieee} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{native+r16-ieee} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{swap+r16-ieee} Swap between little- and big-endian,
+use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{little-endian+r16-ieee} Use the little-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{big-endian+r16-ieee} Use the big-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{r16-ieee} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{native+r16-ieee} Use IEEE 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{swap+r16-ieee} Swap between little- and big-endian,
+use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{little-endian+r16-ieee} Use the little-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{big-endian+r16-ieee} Use the big-endian format for
+unformatted files, use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{r16-ibm} Use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{native+r16-ibm} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{swap+r16-ibm} Swap between little- and big-endian,
+use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{little-endian+r16-ibm} Use the little-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{big-endian+r16-ibm} Use the big-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{r16-ibm} Use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{native+r16-ibm} Use IBM 128-bit format for 
@code{REAL(KIND=16)}.
+@item @code{swap+r16-ibm} Swap between little- and big-endian,
+use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{little-endian+r16-ibm} Use the little-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+@item @code{big-endian+r16-ibm} Use the big-endian format for
+unformatted files, use IBM 128-bit format for @code{REAL(KIND=16)}.
+
  @emph{This option has an effect only when used in the main program.
  The @code{CONVERT} specifier and the GFORTRAN_CONVERT_UNIT environment
  variable override the default specified by @option{-fconvert}.}

Remark: Not sure if the '+' sign is a good idea in an option, or if we
should use something else there.