This patch comes on top of "[patch][v2] libgomp.texi: Document OpenMP's
Interoperability Routines",
https://gcc.gnu.org/pipermail/gcc-patches/2024-August/661314.html
But it documents the code added at "[patch][rfc] libgomp: Add OpenMP
interop support to nvptx + gcn plugin",
https://gcc.gnu.org/pipermail/gcc-patches/2024-August/661207.html
As remarked there: While the code in the plugin should handle the
advertised foreign runtimes (cuda, cuda_driver, hip, hsa) correctly, it
has not been extensively been tested and it only becomes real available
once the 'interop' directive has been implemented in the compiler itself.
Tobias
libgomp.texi: Document supported OpenMP 'interop' types for nvptx and gcn
libgomp/ChangeLog:
* libgomp.texi (omp_get_interop_int, omp_get_interop_str,
omp_get_interop_ptr, omp_get_interop_type_desc): Add @ref to
Offload-Target Specifics.
(Offload-Target Specifics): Document the supported OpenMP
interop types.
libgomp/libgomp.texi | 118 +++++++++++++++++++++++++++++++++++++++++++++++++--
1 file changed, 114 insertions(+), 4 deletions(-)
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index b36b58b6d10..9d76948812a 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -2980,7 +2980,7 @@ not affect the usage of the function when GCC's @code{omp_lib} module or
@item @emph{See also}:
@ref{omp_get_interop_ptr}, @ref{omp_get_interop_str}, @ref{omp_get_interop_rc_desc}
-@c @ref{Offload-Target Specifics}
+@ref{Offload-Target Specifics}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.2,
@@ -3026,7 +3026,7 @@ not affect the usage of the function when GCC's @code{omp_lib} module or
@item @emph{See also}:
@ref{omp_get_interop_int}, @ref{omp_get_interop_str}, @ref{omp_get_interop_rc_desc}
-@c @ref{Offload-Target Specifics}
+@ref{Offload-Target Specifics}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.3,
@@ -3071,7 +3071,7 @@ affect the usage of the function when GCC's @code{omp_lib} module or
@item @emph{See also}:
@ref{omp_get_interop_int}, @ref{omp_get_interop_ptr}, @ref{omp_get_interop_rc_desc}
-@c @ref{Offload-Target Specifics}
+@ref{Offload-Target Specifics}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.4,
@@ -3155,7 +3155,7 @@ affect the usage of the function when GCC's @code{omp_lib} module or
@item @emph{See also}:
@ref{omp_get_num_interop_properties}, @ref{omp_get_interop_name}
-@c @ref{Offload-Target Specifics}
+@ref{Offload-Target Specifics}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.6,
@@ -6747,6 +6747,10 @@ The following sections present notes on the offload-target specifics
@node AMD Radeon
@section AMD Radeon (GCN)
+@menu
+* Foreign-runtime support for AMD GPUs::
+@end menu
+
On the hardware side, there is the hierarchy (fine to coarse):
@itemize
@item work item (thread)
@@ -6816,11 +6820,58 @@ The implementation remark:
pool is exhausted.
@end itemize
+@node Foreign-runtime support for AMD GPUs
+@subsection OpenMP @code{interop} -- Foreign-Runtime Support for AMD GPUs
+
+An interoperability object of OpenMP @code{interop} type can be obtained using
+the @code{interop} directive; supported as foreign runtimes are HIP
+(C++ Heterogeneous-Compute Interface for Portability) and HSA (Heterogeneous
+System Architecture). If no @code{prefer_type} argument has been specified,
+HIP is used.
+
+The following properties can then be extracted using the @ref{Interoperability
+Routines}. Each listed property name has an associated named constant,
+consisting of @code{omp_ipr_} followed by the property name. The following
+table uses ``@emph{int}'', ``@emph{str}'' and ``@emph{ptr}'' to denote the
+routine to be used to obtain the property value.
+
+Available properties for an HIP interop object:
+@multitable @columnfractions .30 .30 .30
+@headitem Property @tab data type @tab value (if constant)
+@item @code{fr_id} @tab @samp{omp_interop_fr_t} @emph{(int)} @tab @samp{omp_fr_hip}
+@item @code{fr_name} @tab @samp{const char *} @emph{(str)} @tab @samp{hip}
+@item @code{vendor} @tab @samp{int} @emph{(int)} @tab @samp{1}
+@item @code{vendor_name} @tab @samp{const char *} @emph{(str)} @tab @samp{amd}
+@item @code{device_num} @tab @samp{int} @emph{(int)} @tab
+@item @code{platform} @tab N/A @tab
+@item @code{device} @tab @samp{hipDevice_t} @emph{(int)} @tab
+@item @code{device_context} @tab @samp{hipCtx_t} @emph{(ptr)} @tab
+@item @code{targetsync} @tab @samp{hipStream_t} @emph{(ptr)} @tab
+@end multitable
+
+Available properties for an HSA interop object:
+@multitable @columnfractions .30 .30 .30
+@headitem Property @tab data type @tab value (if constant)
+@item @code{fr_id} @tab @samp{omp_interop_fr_t} @emph{(int)} @tab @samp{omp_fr_hsa}
+@item @code{fr_name} @tab @samp{const char *} @emph{(str)} @tab @samp{hsa}
+@item @code{vendor} @tab @samp{int} @emph{(int)} @tab @samp{1}
+@item @code{vendor_name} @tab @samp{const char *} @emph{(str)} @tab @samp{amd}
+@item @code{device_num} @tab @samp{int} @emph{(int)} @tab
+@item @code{platform} @tab N/A @tab
+@item @code{device} @tab @samp{hsa_agent *} @emph{(ptr)} @tab
+@item @code{device_context} @tab N/A @tab
+@item @code{targetsync} @tab @samp{hsa_queue *} @emph{(ptr)} @tab
+@end multitable
+
@node nvptx
@section nvptx
+@menu
+* Foreign-runtime support for Nvidia GPUs::
+@end menu
+
On the hardware side, there is the hierarchy (fine to coarse):
@itemize
@item thread
@@ -6903,6 +6954,65 @@ The implementation remark:
pool is exhausted.
@end itemize
+@node Foreign-runtime support for Nvidia GPUs
+@subsection OpenMP @code{interop} -- Foreign-Runtime Support for Nvidia GPUs
+
+An interoperability object of OpenMP @code{interop} type can be obtained using
+the @code{interop} directive; supported as foreign runtimes are the CUDA
+runtime API, the CUDA driver API, and the C++ Heterogeneous-Compute Interface
+for Portability (HIP), which is -- for CUDA-based systems -- a very thin layer
+on top of the CUDA APIs. If no @code{prefer_type} argument has been specified,
+the CUDA runtime API is used.
+
+The following properties can then be extracted using the @ref{Interoperability
+Routines}. Each listed property name has an associated named constant,
+consisting of @code{omp_ipr_} followed by the property name. The following
+table uses ``@emph{int}'', ``@emph{str}'' and ``@emph{ptr}'' to denote the
+routine to be used to obtain the property value.
+
+Available properties for a CUDA runtime API interop object:
+@multitable @columnfractions .30 .30 .30
+@headitem Property @tab data type @tab value (if constant)
+@item @code{fr_id} @tab @samp{omp_interop_fr_t} @emph{(int)} @tab @samp{omp_fr_cuda}
+@item @code{fr_name} @tab @samp{const char *} @emph{(str)} @tab @samp{cuda}
+@item @code{vendor} @tab @samp{int} @emph{(int)} @tab @samp{11}
+@item @code{vendor_name} @tab @samp{const char *} @emph{(str)} @tab @samp{nvidia}
+@item @code{device_num} @tab @samp{int} @emph{(int)} @tab
+@item @code{platform} @tab N/A @tab
+@item @code{device} @tab @samp{int} @emph{(int)} @tab
+@item @code{device_context} @tab N/A @tab
+@item @code{targetsync} @tab @samp{cudaStream_t} @emph{(ptr)} @tab
+@end multitable
+
+Available properties for a CUDA driver API interop object:
+@multitable @columnfractions .30 .30 .30
+@headitem Property @tab data type @tab value (if constant)
+@item @code{fr_id} @tab @samp{omp_interop_fr_t} @emph{(int)} @tab @samp{omp_fr_cuda_driver}
+@item @code{fr_name} @tab @samp{const char *} @emph{(str)} @tab @samp{cuda_driver}
+@item @code{vendor} @tab @samp{int} @emph{(int)} @tab @samp{11}
+@item @code{vendor_name} @tab @samp{const char *} @emph{(str)} @tab @samp{nvidia}
+@item @code{device_num} @tab @samp{int} @emph{(int)} @tab
+@item @code{platform} @tab N/A @tab
+@item @code{device} @tab @samp{CUdevice} @emph{(int)} @tab
+@item @code{device_context} @tab @samp{CUcontext} @emph{(ptr)} @tab
+@item @code{targetsync} @tab @samp{CUstream} @emph{(ptr)} @tab
+@end multitable
+
+Available properties for an HIP interop object:
+@multitable @columnfractions .30 .30 .30
+@headitem Property @tab data type @tab value (if constant)
+@item @code{fr_id} @tab @samp{omp_interop_fr_t} @emph{(int)} @tab @samp{omp_fr_hip}
+@item @code{fr_name} @tab @samp{const char *} @emph{(str)} @tab @samp{hip}
+@item @code{vendor} @tab @samp{int} @emph{(int)} @tab @samp{11}
+@item @code{vendor_name} @tab @samp{const char *} @emph{(str)} @tab @samp{nvidia}
+@item @code{device_num} @tab @samp{int} @emph{(int)} @tab
+@item @code{platform} @tab N/A @tab
+@item @code{device} @tab @samp{hipDevice_t} @emph{(int)} @tab
+@item @code{device_context} @tab @samp{hipCtx_t} @emph{(ptr)} @tab
+@item @code{targetsync} @tab @samp{hipStream_t} @emph{(ptr)} @tab
+@end multitable
+
+
@c ---------------------------------------------------------------------
@c The libgomp ABI
