[fortran,doc] Mention new CONVERT options for POWER

Message ID c5d8b93f-c039-e4cb-7ea6-cdb4e2502f42@netcologne.de
State Committed
Commit 1a5ae012ff3303a8232a03ac9a0925c709775076
Headers
Series [fortran,doc] Mention new CONVERT options for POWER |

Commit Message

Thomas Koenig April 27, 2022, 8:34 p.m. UTC
  Hi,

as we say in German "Nicht documentiert ist nicht gemacht", if
it is not documented, it wasn't done.

So I thought it would be time to document the changes to the various
ways of specifying CONVERT before gcc12 went out of the door, so
here is a patch for that.

If that goes in, I will also write up something for gcc-12/changes.html.

OK for trunk?  Suggestions for improvements?

Best regards

	Thomas

Document changes to CONVERT for -mabi-ieeelongdouble for POWER

gcc/fortran/ChangeLog:

	* gfortran.texi: Mention r16_ieee and r16_ibm.
	* invoke.texi: Likewise.
  

Comments

Richard Biener April 28, 2022, 7:20 a.m. UTC | #1
On Wed, Apr 27, 2022 at 10:34 PM Thomas Koenig via Fortran
<fortran@gcc.gnu.org> wrote:
>
> Hi,
>
> as we say in German "Nicht documentiert ist nicht gemacht", if
> it is not documented, it wasn't done.
>
> So I thought it would be time to document the changes to the various
> ways of specifying CONVERT before gcc12 went out of the door, so
> here is a patch for that.
>
> If that goes in, I will also write up something for gcc-12/changes.html.
>
> OK for trunk?  Suggestions for improvements?

OK for trunk.

Richard.

> Best regards
>
>         Thomas
>
> Document changes to CONVERT for -mabi-ieeelongdouble for POWER
>
> gcc/fortran/ChangeLog:
>
>         * gfortran.texi: Mention r16_ieee and r16_ibm.
>         * invoke.texi: Likewise.
  
Bernhard Reutner-Fischer April 28, 2022, 5:17 p.m. UTC | #2
Hi Thomas,

On 27 April 2022 22:34:39 CEST, Thomas Koenig via Fortran <fortran@gcc.gnu.org> wrote:

+@item @code{'big_endian'}  Do all unformatted I/O in big_endian mod.e


ISTM that this should be s/mod.e/mode./ ?
thanks,
  
Thomas Koenig April 29, 2022, 6:03 p.m. UTC | #3
On 28.04.22 19:17, Bernhard Reutner-Fischer wrote:
> ISTM that this should be s/mod.e/mode./ ?

Yep, fixed as obvious and simple on trunk with
r13-49-g4a8b45e8bc8246bd141dad65f571a3e0cc499c6b .

OK for backport to gcc-12? (This is both extremely safe and
not particularly important :-)

Best regards

	Thomas
  
Bernhard Reutner-Fischer April 29, 2022, 11:26 p.m. UTC | #4
On Fri, 29 Apr 2022 20:03:55 +0200
Thomas Koenig <tkoenig@netcologne.de> wrote:

> On 28.04.22 19:17, Bernhard Reutner-Fischer wrote:
> > ISTM that this should be s/mod.e/mode./ ?  
> 
> Yep, fixed as obvious and simple on trunk with
> r13-49-g4a8b45e8bc8246bd141dad65f571a3e0cc499c6b .

thanks!
> 
> OK for backport to gcc-12? (This is both extremely safe and
> not particularly important :-)

I'd say yes because it's 1) doc 2) trivial 3) obvious :)

But formally, i think RM approval is needed ATM.
Richard?
  
Richard Biener May 2, 2022, 6:32 a.m. UTC | #5
On Sat, Apr 30, 2022 at 1:26 AM Bernhard Reutner-Fischer
<rep.dot.nop@gmail.com> wrote:
>
> On Fri, 29 Apr 2022 20:03:55 +0200
> Thomas Koenig <tkoenig@netcologne.de> wrote:
>
> > On 28.04.22 19:17, Bernhard Reutner-Fischer wrote:
> > > ISTM that this should be s/mod.e/mode./ ?
> >
> > Yep, fixed as obvious and simple on trunk with
> > r13-49-g4a8b45e8bc8246bd141dad65f571a3e0cc499c6b .
>
> thanks!
> >
> > OK for backport to gcc-12? (This is both extremely safe and
> > not particularly important :-)
>
> I'd say yes because it's 1) doc 2) trivial 3) obvious :)
>
> But formally, i think RM approval is needed ATM.
> Richard?

OK.
  

Patch

diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index f8737f4d323..6f622fb9898 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -589,7 +589,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
@@ -686,11 +686,12 @@  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
+most systems is:
 @smallexample
 GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
 mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
@@ -711,14 +712,24 @@  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 which support @option{-mabi=ieeelongdouble},
+there are additional options, which can be combined with the
+others with commas. Those are
+@itemize @w{}
+@item @code{R16_IEEE} Use IEEE 128-bit format for @code{REAL(KIND=16)}.
+@item @code{R16_IBM} Use IBM @code{long double} format for
+@code{REAL(KIND=16)}.
+@end itemize
 A missing mode for an exception is taken to mean @code{BIG_ENDIAN}.
 Examples of values for @env{GFORTRAN_CONVERT_UNIT} are:
 @itemize @w{}
-@item @code{'big_endian'}  Do all unformatted I/O in big_endian mode.
+@item @code{'big_endian'}  Do all unformatted I/O in big_endian mod.e
 @item @code{'little_endian;native:10-20,25'}  Do all unformatted I/O
 in little_endian mode, except for units 10 to 20 and 25, which are in
 native format.
 @item @code{'10-20'}  Units 10 to 20 are big-endian, the rest is native.
+@item @code{'big_endian,r16_ibm'} Do all unformatted I/O in big-endian
+mode and use IBM long double for output of @code{REAL(KIND=16)} values.
 @end itemize
 
 Setting the environment variables should be done on the command
@@ -1736,7 +1747,7 @@  the @code{CONVERT} specifier on the @code{OPEN} statement.
 @xref{GFORTRAN_CONVERT_UNIT}, for an alternative way of specifying
 the data format via an environment variable.
 
-Valid values for @code{CONVERT} are:
+Valid values for @code{CONVERT} on most systems are:
 @itemize @w{}
 @item @code{CONVERT='NATIVE'} Use the native format.  This is the default.
 @item @code{CONVERT='SWAP'} Swap between little- and big-endian.
@@ -1745,6 +1756,15 @@  for unformatted files.
 @item @code{CONVERT='BIG_ENDIAN'} Use the big-endian representation for
 unformatted files.
 @end itemize
+On POWER systems which support @option{-mabi=ieeelongdouble},
+there are additional options, which can be combined with the others
+with commas. Those are
+@itemize @w{}
+@item @code{CONVERT='R16_IEEE'} Use IEEE 128-bit format for
+@code{REAL(KIND=16)}.
+@item @code{CONVERT='R16_IBM'} Use IBM @code{long double} format for
+real@code{REAL(KIND=16)}.
+@end itemize
 
 Using the option could look like this:
 @smallexample
diff --git a/gcc/fortran/invoke.texi b/gcc/fortran/invoke.texi
index 5c7501a28b1..c0932f6cd70 100644
--- a/gcc/fortran/invoke.texi
+++ b/gcc/fortran/invoke.texi
@@ -1435,10 +1435,20 @@  These options affect the runtime behavior of programs compiled with GNU Fortran.
 @item -fconvert=@var{conversion}
 @opindex @code{fconvert=}@var{conversion}
 Specify the representation of data for unformatted files.  Valid
-values for conversion are: @samp{native}, the default; @samp{swap},
-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.
+values for conversion on most systems are: @samp{native}, the default;
+@samp{swap}, 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.
+
+On POWER systems which suppport @option{-mabi=ieeelongdouble},
+there are additional options, which can be combined with others with
+commas.  Those are
+@itemize @w{}
+@item @option{-fconvert=r16_ieee} Use IEEE 128-bit format for
+@code{REAL(KIND=16)}.
+@item @option{-fconvert=r16_ibm} Use IBM long double format for
+@code{REAL(KIND=16)}.
+@end itemize
 
 @emph{This option has an effect only when used in the main program.
 The @code{CONVERT} specifier and the GFORTRAN_CONVERT_UNIT environment