[gcc r16-1100] libgomp.texi (omp_interop_*): Add note about 5.2-to-6.0 incompatibility

[Tobias Burnus]

https://gcc.gnu.org/g:0f56d67a498fb5f6223c36589bb1f5d7ae219e45

commit r16-1100-g0f56d67a498fb5f6223c36589bb1f5d7ae219e45
Author: Tobias Burnus <tburnus@baylibre.com>
Date:   Wed Jun 4 13:25:05 2025 +0200

    libgomp.texi (omp_interop_*): Add note about 5.2-to-6.0 incompatibility
    
    GCC uses the 6.0 types - which are unfortunately not quite compatible with
    code expecting 5.1/5.2 data types.  Therefore, this commit adds a note to
    hopefully reduce surprises. Namely:
    
    For C/C++: while OpenMP 5.1 and 5.2 used 'int *ret_code', OpenMP 6.0 uses
    'omp_interop_rc_t *ret_code' in omp_interop_{int,ptr,str} and 'int' instead
    of 'omp_interop_rc_t ret_code' in omp_get_interop_rc_desc.
    
    Neither C nor C++ like passing the wrong pointer type, albeit for C, GCC < 14
    and clang only warn (gcc >= r14-6037-g9715c545d33b3a has an error) and
    using -fpermissive turns it into a warning and -Wno-incompatible-pointer-types
    silences it for C.
    
    C++ also dislikes passing an int to an enum, albeit -fpermissive turns the
    error into a warning with g++ (but not clang++). And, here, using an enum
    on the caller side works with both int and enum on the callee side.
    
    libgomp/ChangeLog:
    
            * libgomp.texi (omp_interop_{int,ptr,str,rc_desc}): Add note about
            the 'ret_code' type change in OpenMP 6.
    
    Co-authored-by: Sandra Loosemore <sloosemore@baylibre.com>

Diff:
---
 libgomp/libgomp.texi | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 8e487bcd168c..7116fcda13fe 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -3130,6 +3130,11 @@ and Fortran or used with @code{NULL} as argument in C and C++.  If successful,
 In GCC, the effect of running this routine in a @code{target} region that is not
 the initial device is unspecified.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int*} was used for the @var{ret_code} argument
+in place of a pointer to the enumerated type @code{omp_interop_rc_t}.
+
 @c Implementation remark: In GCC, the Fortran interface differs from the one shown
 @c below: the function has C binding and @var{interop} and @var{property_id} are
 @c passed by value, which permits use of the same ABI as the C function.  This does
@@ -3176,6 +3181,11 @@ and Fortran or used with @code{NULL} as argument in C and C++.  If successful,
 In GCC, the effect of running this routine in a @code{target} region that is not
 the initial device is unspecified.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int*} was used for the @var{ret_code} argument
+in place of a pointer to the enumerated type @code{omp_interop_rc_t}.
+
 @c Implementation remark: In GCC, the Fortran interface differs from the one shown
 @c below: the function has C binding and @var{interop} and @var{property_id} are
 @c passed by value, which permits use of the same ABI as the C function.  This does
@@ -3222,6 +3232,11 @@ and Fortran or used with @code{NULL} as argument in C and C++.  If successful,
 In GCC, the effect of running this routine in a @code{target} region that is not
 the initial device is unspecified.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int*} was used for the @var{ret_code} argument
+in place of a pointer to the enumerated type @code{omp_interop_rc_t}.
+
 @c Implementation remark: In GCC, the Fortran interface differs from the one shown
 @c below: @var{interop} and @var{property_id} are passed by value.  This does not
 @c affect the usage of the function when GCC's @code{omp_lib} module or
@@ -3348,6 +3363,11 @@ the @var{ret_code} in human-readable form.
 The behavior is unspecified if value of @var{ret_code} was not set by an
 interoperability routine invoked for @var{interop}.
 
+GCC implements the OpenMP 6.0 version of this function for C and C++, which is not
+compatible with its type signature in previous versions of the OpenMP specification.
+In older versions, the type @code{int} was used for the @var{ret_code} argument
+in place of the enumerated type @code{omp_interop_rc_t}.
+
 @item @emph{C/C++}:
 @multitable @columnfractions .20 .80
 @item @emph{Prototype}: @tab @code{const char *omp_get_interop_rc_desc(const omp_interop_t interop,