[Bug fortran/57871] New: gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[Bug fortran/57871] New: gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[john.harper at vuw dot ac.nz]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

            Bug ID: 57871
           Summary: gfortran -freal-4-real-16 gives wrong result for
                    selected_real_kind(1)
           Product: gcc
           Version: 4.8.1
            Status: UNCONFIRMED
          Severity: normal
          Priority: P3
         Component: fortran
          Assignee: unassigned at gcc dot gnu.org
          Reporter: john.harper at vuw dot ac.nz

gfortran 4.8.1 -freal-4-real-16 gives real(16) kind with selected_real_kind(1)
but it ought to give real(8) because that is the smallest decimal precision
available with that compiler option. Same problem with -freal-4-real-10 giving
real(10) instead of real(8). Evidence:

cayley[~/Jfh] % cat testprecision.f90
implicit none
integer,parameter:: p1 = selected_real_kind(1), dp = kind(1d0)
print *,'kind(1.0_p1)',kind(1.0_p1),'precision(1.0_p1)',precision(1.0_p1)
print *,'kind(1.0_dp)',kind(1.0_dp),'precision(1.0_dp)',precision(1.0_dp)
end
cayley[~/Jfh] % /local/scratch/gf/bin/gfortran -freal-4-real-16 -Wall -Wextra
-fno-strict-aliasing -fwrapv testprecision.f90
cayley[~/Jfh] % ./a.out
 kind(1.0_p1)          16 precision(1.0_p1)          33
 kind(1.0_dp)           8 precision(1.0_dp)          15
cayley[~/Jfh] % /local/scratch/gf/bin/gfortran -freal-4-real-10 -Wall -Wextra
-fno-strict-aliasing -fwrapv testprecision.f90
cayley[~/Jfh] % ./a.out                                                         
 kind(1.0_p1)          10 precision(1.0_p1)          18
 kind(1.0_dp)           8 precision(1.0_dp)          15
cayley[~/Jfh] % /local/scratch/gf/bin/gfortran -v
Using built-in specs.
COLLECT_GCC=/local/scratch/gf/bin/gfortran
COLLECT_LTO_WRAPPER=/local/scratch/gf/libexec/gcc/x86_64-unknown-linux-gnu/4.8.1/lto-wrapper
Target: x86_64-unknown-linux-gnu                                                
Configured with: /local/scratch/gcc-4.8-20130530/configure
--prefix=/local/scratch/gf --enable-languages=c,fortran --disable-libada
--with-local-prefix=/local/scratch --with-gmp=/local/scratch                    
Thread model: posix                                                             
gcc version 4.8.1 20130530 (prerelease) (GCC)                                   
cayley[~/Jfh] %

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[dominiq at lps dot ens.fr]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

Dominique d'Humieres <dominiq at lps dot ens.fr> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|UNCONFIRMED                 |RESOLVED
         Resolution|---                         |INVALID

--- Comment #1 from Dominique d'Humieres <dominiq at lps dot ens.fr> ---
> gfortran 4.8.1 -freal-4-real-16 gives real(16) kind with 
> selected_real_kind(1) but it ought to give real(8) because that is 
> the smallest decimal precision available with that compiler option. 
> Same problem with -freal-4-real-10 giving real(10) instead of real(8). ...

Why are you expecting that? The manual says:

-freal-4-real-8
-freal-4-real-10
-freal-8-real-4
-freal-8-real-10
-freal-8-real-16
Promote all REAL(KIND=M) entities to REAL(KIND=N) entities. If REAL(KIND=N) is
unavailable, then an error will be issued. All other real kind types are
unaffected by this option. These options should be used with care and may not
be suitable for your codes. Areas of possible concern include calls to external
procedures, alignment in EQUIVALENCE and/or COMMON, generic interfaces, BOZ
literal constant conversion, and I/O. Inspection of the intermediate
representation of the translated Fortran code, produced by
-fdump-tree-original, is suggested. 

and your example does exactly that: Closing as INVALID.

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[kargl at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

kargl at gcc dot gnu.org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|RESOLVED                    |REOPENED
   Last reconfirmed|                            |2013-07-10
                 CC|                            |kargl at gcc dot gnu.org
         Resolution|INVALID                     |---
     Ever confirmed|0                           |1

--- Comment #2 from kargl at gcc dot gnu.org ---
(In reply to Dominique d'Humieres from comment #1)
> > gfortran 4.8.1 -freal-4-real-16 gives real(16) kind with 
> > selected_real_kind(1) but it ought to give real(8) because that is 
> > the smallest decimal precision available with that compiler option. 
> 
> and your example does exactly that: Closing as INVALID.

I think that you may have been a little too hasty in closing
this PR.  The issue lies in the code for selected_real_kind.

  implicit none
  integer,parameter:: p1 = selected_real_kind(1)

This initialization expression is requesting the type with
smallest precision that exceeds 1.  With -freal-4-real-16,
that type is double precision (ie kind=8).  The problem
lies in gfc_simplify_selected_real_kind.  It has no knowledge
of the -freal-*-real-* options.  The loop (lines 5447-5457)

  for (i = 0; gfc_real_kinds[i].kind != 0; i++)
    {
      if (gfc_real_kinds[i].precision >= precision)
        found_precision = 1;

      if (gfc_real_kinds[i].range >= range)
        found_range = 1;

      if (gfc_real_kinds[i].radix >= radix)
        found_radix = 1;

      if (gfc_real_kinds[i].precision >= precision
      && gfc_real_kinds[i].range >= range
      && gfc_real_kinds[i].radix >= radix && gfc_real_kinds[i].kind < kind)
    kind = gfc_real_kinds[i].kind;
    }

searchs the ordered set [24, 53, 53, 113] (on FreeBSD-i386) or
[24, 53, 64, 113] (on FreeBSD-amd64).  In either case, the
initialization expression returns REAL(4).  However, with
-freal-4-real-16,  one might expect the ordered set to be
searched is [113, 53, 64, 113] as REAL(4) has been promoted
to REAL(16).

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[sgk at troutmask dot apl.washington.edu]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #3 from Steve Kargl <sgk at troutmask dot apl.washington.edu> ---
On Wed, Jul 10, 2013 at 05:42:03PM +0000, kargl at gcc dot gnu.org wrote:
>   implicit none
>   integer,parameter:: p1 = selected_real_kind(1)
> 
> This initialization expression is requesting the type with
> smallest precision that exceeds 1.  With -freal-4-real-16,
> that type is double precision (ie kind=8).  The problem
> lies in gfc_simplify_selected_real_kind.  It has no knowledge
> of the -freal-*-real-* options.  The loop (lines 5447-5457)

(remove loop code)

> searchs the ordered set [24, 53, 53, 113] (on FreeBSD-i386) or
> [24, 53, 64, 113] (on FreeBSD-amd64).  In either case, the
> initialization expression returns REAL(4).  However, with
> -freal-4-real-16,  one might expect the ordered set to be
> searched is [113, 53, 64, 113] as REAL(4) has been promoted
> to REAL(16).

The results of running John's code are odder than what one
might expect.

The normal results:

% gfc4x -o foo foo.f90 && ./foo
 kind(1.0_p1)           4 precision(1.0_p1)           6
 kind(1.0_dp)           8 precision(1.0_dp)          15

One might expect the first line to be 8 and 15, respectively.

% gfc4x -o foo foo.f90 -freal-4-real-16 && ./foo
 kind(1.0_p1)          16 precision(1.0_p1)          33
 kind(1.0_dp)           8 precision(1.0_dp)          15

Here the default real kind is promoted to REAL(8), but literal
constants declared with a kind type suffix are not promoted.
The first line is the correct output, although one might
anticipate 8 and 15.  But, what may be surprising is that the 
double precision kind has been bumped to quad precision. 

troutmask:sgk[207] gfc4x -o foo foo.f90 -fdefault-real-8 && ./foo
 kind(1.0_p1)           4 precision(1.0_p1)           6
 kind(1.0_dp)          16 precision(1.0_dp)          33

I've always hated these type options as a lzy programmer's
crutch who refuses to properly port an algorithm from 
one precision to another.

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[harper at msor dot vuw.ac.nz]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #4 from harper at msor dot vuw.ac.nz ---
The reason I sent that bug report is that I had read the manual and
found that -freal-4-real-16 makes the available real kinds 8, 10, 16.
The Fortran standard says selected_real_kind(1) must give the kind with
the smallest available decimal precision that has precison at least 1. 
In the circumstances that is kind 8. The manual refers to promotion of
REAL(KIND=M) entities. Selected_real_kind is an integer entity not a
real one.

On Wed, 10 Jul 2013, dominiq at lps dot ens.fr wrote:

> Date: Wed, 10 Jul 2013 13:07:40 +0000
> From: dominiq at lps dot ens.fr <gcc-bugzilla@gcc.gnu.org>
> To: john.harper@vuw.ac.nz
> Subject: [Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for
>     selected_real_kind(1)
> Resent-Date: Wed, 10 Jul 2013 13:08:02 +0000
> Resent-From: <john.harper@vuw.ac.nz>
> 
> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871
>
> Dominique d'Humieres <dominiq at lps dot ens.fr> changed:
>
>           What    |Removed                     |Added
> ----------------------------------------------------------------------------
>             Status|UNCONFIRMED                 |RESOLVED
>         Resolution|---                         |INVALID
>
> --- Comment #1 from Dominique d'Humieres <dominiq at lps dot ens.fr> ---
>> gfortran 4.8.1 -freal-4-real-16 gives real(16) kind with
>> selected_real_kind(1) but it ought to give real(8) because that is
>> the smallest decimal precision available with that compiler option.
>> Same problem with -freal-4-real-10 giving real(10) instead of real(8). ...
>
> Why are you expecting that? The manual says:
>
> -freal-4-real-8
> -freal-4-real-10
> -freal-8-real-4
> -freal-8-real-10
> -freal-8-real-16
> Promote all REAL(KIND=M) entities to REAL(KIND=N) entities. If REAL(KIND=N) is
> unavailable, then an error will be issued. All other real kind types are
> unaffected by this option. These options should be used with care and may not
> be suitable for your codes. Areas of possible concern include calls to external
> procedures, alignment in EQUIVALENCE and/or COMMON, generic interfaces, BOZ
> literal constant conversion, and I/O. Inspection of the intermediate
> representation of the translated Fortran code, produced by
> -fdump-tree-original, is suggested.
>
> and your example does exactly that: Closing as INVALID.
>
> -- 
> You are receiving this mail because:
> You reported the bug.
>
>
>


-- John Harper, School of Mathematics Statistics and Operations Research
Victoria University, PO Box 600, Wellington 6140, New Zealand
e-mail john.harper@vuw.ac.nz phone (+64)(4)463 5276 fax (+64)(4)463 5045

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[harper at msor dot vuw.ac.nz]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #5 from harper at msor dot vuw.ac.nz ---
I have now found two more oddities of type promotion but I don't claim 
that these are gfortran bugs, only that the mmanual might need amending.

Oddity 1. Although -freal-4-real-8 does what the manual implies with
the program below (making the real kinds 8,10,16 on an x86_64 system),
-fdefault-real-8 keeps the available kinds at 4,8,10,16 but merely
changes the defaults. I suggest that the following sentence 
be added to the manual sewction on -fdefault-real-8 at the end:

If "REAL(KIND=4)" is a real type available with no -f options, then it
remains available with -fdefault-real-8 though not with -freal-4-real-8.

Oddity 2. If one uses -fdefault-double-8 in a system where default real
was 4 bytes wide then one must also use -fdefault-real-8. The manual
entries for -fdefault-double-8 and -fdefault-real-8 are both silent 
on what happens if -fdefault-double-8 is given but -fdefault-real-8 is 
not. I won't suggest an amendment here because I don't know what happens 
in a system whose default real with no -f options was 8 bytes wide.

Evidence:

cayley[~/Jfh] % cat gfkinds.f90
implicit none
real     xdefault
real(4 ) x4
real(8 ) x8
real(10) x10
real(16) x16
print *,kind(xdefault),kind(x4),kind(x8),kind(x10),kind(x16)
end
cayley[~/Jfh] % gf -freal-4-real-8 gfkinds.f90
cayley[~/Jfh] % ./a.out
            8           8           8          10          16
cayley[~/Jfh] % gf -fdefault-real-8 gfkinds.f90
cayley[~/Jfh] % ./a.out
            8           4           8          10          16
cayley[~/Jfh] % gf -fdefault-double-8 gfkinds.f90
<built-in>:0:0: fatal error: Use of -fdefault-double-8 requires 
-fdefault-real-8
compilation terminated.
cayley[~/Jfh] % alias gf
/local/scratch/gf/bin/gfortran
cayley[~/Jfh] % gf -v
Using built-in specs.
COLLECT_GCC=/local/scratch/gf/bin/gfortran
COLLECT_LTO_WRAPPER=/local/scratch/gf/libexec/gcc/x86_64-unknown-linux-gnu/4.8.1/lto-wrapper
Target: x86_64-unknown-linux-gnu
Configured with: /local/scratch/gcc-4.8-20130530/configure 
--prefix=/local/scratch/gf --enable-languages=c,fortran --disable-libada 
--with-local-prefix=/local/scratch --with-gmp=/local/scratch
Thread model: posix
gcc version 4.8.1 20130530 (prerelease) (GCC)
cayley[~/Jfh] %


On Wed, 10 Jul 2013, sgk at troutmask dot apl.washington.edu wrote:

> Date: Wed, 10 Jul 2013 20:02:43 +0000
> From: sgk at troutmask dot apl.washington.edu <gcc-bugzilla@gcc.gnu.org>
> To: john.harper@vuw.ac.nz
> Subject: [Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for
>     selected_real_kind(1)
> Resent-Date: Wed, 10 Jul 2013 20:02:59 +0000
> Resent-From: <john.harper@vuw.ac.nz>
> 
> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871
>
> --- Comment #3 from Steve Kargl <sgk at troutmask dot apl.washington.edu> ---
> On Wed, Jul 10, 2013 at 05:42:03PM +0000, kargl at gcc dot gnu.org wrote:
>>   implicit none
>>   integer,parameter:: p1 = selected_real_kind(1)
>>
>> This initialization expression is requesting the type with
>> smallest precision that exceeds 1.  With -freal-4-real-16,
>> that type is double precision (ie kind=8).  The problem
>> lies in gfc_simplify_selected_real_kind.  It has no knowledge
>> of the -freal-*-real-* options.  The loop (lines 5447-5457)
>
> (remove loop code)
>
>> searchs the ordered set [24, 53, 53, 113] (on FreeBSD-i386) or
>> [24, 53, 64, 113] (on FreeBSD-amd64).  In either case, the
>> initialization expression returns REAL(4).  However, with
>> -freal-4-real-16,  one might expect the ordered set to be
>> searched is [113, 53, 64, 113] as REAL(4) has been promoted
>> to REAL(16).
>
> The results of running John's code are odder than what one
> might expect.
>
> The normal results:
>
> % gfc4x -o foo foo.f90 && ./foo
> kind(1.0_p1)           4 precision(1.0_p1)           6
> kind(1.0_dp)           8 precision(1.0_dp)          15
>
> One might expect the first line to be 8 and 15, respectively.
>
> % gfc4x -o foo foo.f90 -freal-4-real-16 && ./foo
> kind(1.0_p1)          16 precision(1.0_p1)          33
> kind(1.0_dp)           8 precision(1.0_dp)          15
>
> Here the default real kind is promoted to REAL(8), but literal
> constants declared with a kind type suffix are not promoted.
> The first line is the correct output, although one might
> anticipate 8 and 15.  But, what may be surprising is that the
> double precision kind has been bumped to quad precision.
>
> troutmask:sgk[207] gfc4x -o foo foo.f90 -fdefault-real-8 && ./foo
> kind(1.0_p1)           4 precision(1.0_p1)           6
> kind(1.0_dp)          16 precision(1.0_dp)          33
>
> I've always hated these type options as a lzy programmer's
> crutch who refuses to properly port an algorithm from
> one precision to another.
>
> -- 
> You are receiving this mail because:
> You reported the bug.
>
>
>


-- John Harper, School of Mathematics Statistics and Operations Research
Victoria University, PO Box 600, Wellington 6140, New Zealand
e-mail john.harper@vuw.ac.nz phone (+64)(4)463 5276 fax (+64)(4)463 5045

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[sgk at troutmask dot apl.washington.edu]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #6 from Steve Kargl <sgk at troutmask dot apl.washington.edu> ---
On Thu, Jul 11, 2013 at 10:30:04PM +0000, harper at msor dot vuw.ac.nz wrote:
> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871
> 
> --- Comment #5 from harper at msor dot vuw.ac.nz ---
> I have now found two more oddities of type promotion but I don't claim 
> that these are gfortran bugs, only that the mmanual might need amending.
> 
> Oddity 1. Although -freal-4-real-8 does what the manual implies with
> the program below (making the real kinds 8,10,16 on an x86_64 system),
> -fdefault-real-8 keeps the available kinds at 4,8,10,16 but merely
> changes the defaults. I suggest that the following sentence 
> be added to the manual sewction on -fdefault-real-8 at the end:
> 
> If "REAL(KIND=4)" is a real type available with no -f options, then it
> remains available with -fdefault-real-8 though not with -freal-4-real-8.
> 
> Oddity 2. If one uses -fdefault-double-8 in a system where default real
> was 4 bytes wide then one must also use -fdefault-real-8. The manual
> entries for -fdefault-double-8 and -fdefault-real-8 are both silent 
> on what happens if -fdefault-double-8 is given but -fdefault-real-8 is 
> not. I won't suggest an amendment here because I don't know what happens 
> in a system whose default real with no -f options was 8 bytes wide.

I am not at all surprised by your findings.  I would personally
like to deprecate the -fdefault-* options.  These options do
not necessarily do what a user may expect.  The options require
care with EQUIVALENCE, COMMON, and may even require one to
rebuild the runtime library (if one is doing double precision
IO).  Most users don't understand the limitations, and simply
use these options as a quick-n-dirty way to port single
precision code to double precision.  Unfortunately, the -fdefault-*
options are too ingrained into peoples brains.

The -freal-* options were a later attempt to try to fix
the deficiencies with the -fdefault-* options.  These 
family of option should not be mixed.  I suppose this
should be documented.

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[kargl at gcc dot gnu.org]

http://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

kargl at gcc dot gnu.org changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|kargl at gcc dot gnu.org           |

--- Comment #7 from kargl at gcc dot gnu.org ---
Remove myself from cc list.

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[dominiq at lps dot ens.fr]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #9 from Dominique d'Humieres <dominiq at lps dot ens.fr> ---
Note that after r11-7501 the test in comment O gives cat run time:

% gfc pr57871.f90 -freal-4-real-16
% ./a.out
 kind(1.0_p1)           4 precision(1.0_p1)           6
 kind(1.0_dp)           8 precision(1.0_dp)          15

instead of

% gfca pr57871.f90 -freal-4-real-16
% ./a.out
 kind(1.0_p1)          16 precision(1.0_p1)          33
 kind(1.0_dp)           8 precision(1.0_dp)          15

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[cvs-commit at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #10 from CVS Commits <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Tobias Burnus <burnus@gcc.gnu.org>:

https://gcc.gnu.org/g:80cf2facbbdafed159b326d83f7cf3999c3df8d0

commit r11-7519-g80cf2facbbdafed159b326d83f7cf3999c3df8d0
Author: Tobias Burnus <tobias@codesourcery.com>
Date:   Fri Mar 5 10:43:11 2021 +0100

    Fortran: Follow fixes to -freal-{4,8}-real* handling [PR99355,PR57871]

    gcc/fortran/ChangeLog:

            PR fortran/99355
            PR fortran/57871
            * invoke.texi (-freal{4,8}-real-*): Extend description.
            * primary.c (match_real_constant): Also promote real literals
            with '_kind' number.

    gcc/testsuite/ChangeLog:

            * gfortran.dg/real4-10-real8-10.f90: Add check for real literals
            with '_kind' number.
            * gfortran.dg/real4-10-real8-16.f90: Likewise.
            * gfortran.dg/real4-10-real8-4.f90: Likewise.
            * gfortran.dg/real4-10.f90: Likewise.
            * gfortran.dg/real4-16-real8-10.f90: Likewise.
            * gfortran.dg/real4-16-real8-16.f90: Likewise.
            * gfortran.dg/real4-16-real8-4.f90: Likewise.
            * gfortran.dg/real4-16.f90: Likewise.
            * gfortran.dg/real4-8-real8-10.f90: Likewise.
            * gfortran.dg/real4-8-real8-16.f90: Likewise.
            * gfortran.dg/real4-8-real8-4.f90: Likewise.
            * gfortran.dg/real4-8.f90: Likewise.
            * gfortran.dg/real8-10.f90: Likewise.
            * gfortran.dg/real8-16.f90: Likewise.
            * gfortran.dg/real8-4.f90: Likewise.

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[burnus at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

Tobias Burnus <burnus at gcc dot gnu.org> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |burnus at gcc dot gnu.org

--- Comment #11 from Tobias Burnus <burnus at gcc dot gnu.org> ---
(In reply to Dominique d'Humieres from comment #9)
> Note that after r11-7501 the test in comment O gives cat run time:
> % gfc pr57871.f90 -freal-4-real-16

That issue is now fixed – see PR fortran/99355 for some details.

I also updated the documentation to fill some gaps in the
-freal-4-real-16 etc. descriptions and added another caveat. See commit or
https://gcc.gnu.org/onlinedocs/gfortran/Fortran-Dialect-Options.html#index-freal-4-real-16
(may take a day to get updated).


As this issue is about documentation, if I read the later comments correctly:
Can you check whether the documentation is now sufficient or whether more is
needed? If so, what is needed? — If not, can this bug now be closed?

[Bug fortran/57871] gfortran -freal-4-real-16 gives wrong result for selected_real_kind(1)

[dominiq at lps dot ens.fr]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=57871

--- Comment #12 from Dominique d'Humieres <dominiq at lps dot ens.fr> ---
> As this issue is about documentation, if I read the later comments correctly:
> Can you check whether the documentation is now sufficient or whether more is needed? > If so, what is needed? — If not, can this bug now be closed?

I don't like the sentence

Note that for @code{REAL(KIND=KIND(1.0))} the literal may get promoted and
then the result may get promoted again.

There is only one promotion for -freal-4-real-X, and it does not matter if
1.0 is promoted first KIND(1.0) is then X, or after KIND(1.0) is 4 then 
REAL(KIND=4) is promoted to REAL(KIND=X).

The situation for SELECTED_REAL_KIND(1) is quite different: if the promotion of
-freal-4-real-X is done first, then the smallest kind available is 8,
if it is done after then SELECTED_REAL_KIND(1) will be 4, then promoted to X.

What about a sentence such as:

Note that while @code{REAL(KIND=KIND(1.0))} is always promoted to X by
-freal-4-real-X, @code{SELECTED_REAL_KIND(1)} returns always 4 which is then
promoted to X.

?

It may be also useful to add a sentence saying that the promotion options are
provided as such and that the observed behavior is not a bug but a feature.

As said in comment 8, I did not find any other circonstance, by
SELECTED_REAL_KIND
for which such ambiguity exists.