From patchwork Wed Aug 21 17:57:27 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 1975060 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=baylibre-com.20230601.gappssmtp.com header.i=@baylibre-com.20230601.gappssmtp.com header.a=rsa-sha256 header.s=20230601 header.b=p9jFK4ba; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=2620:52:3:1:0:246e:9693:128c; helo=server2.sourceware.org; envelope-from=gcc-patches-bounces~incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4WpvFM2XBPz1yYZ for ; Thu, 22 Aug 2024 03:57:59 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 155A4386F83F for ; Wed, 21 Aug 2024 17:57:57 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-ed1-x531.google.com (mail-ed1-x531.google.com [IPv6:2a00:1450:4864:20::531]) by sourceware.org (Postfix) with ESMTPS id 392313860008 for ; Wed, 21 Aug 2024 17:57:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 392313860008 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=baylibre.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=baylibre.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 392313860008 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2a00:1450:4864:20::531 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1724263056; cv=none; b=j7eI31KNah2SlW0vC2WAdBxPrDD3FvmokJgVOJx3RYrwzg/RcaScU4J2s55171EUmPqlyg7WtPVZ38Z55/QXm42yvg4AmJo4yJgz7w9Uiv18eJRbOnAzhqiSEacpg+D3W0tEs4y+JYLYo4sZzr4Brcw7BTRv0RjeQ8LVHuVxGYY= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1724263056; c=relaxed/simple; bh=ycov4wzqJaOwGZQmxJhJ9j5w/tgmqWVFvzbEPEhA4QU=; h=DKIM-Signature:Message-ID:Date:MIME-Version:To:From:Subject; b=nzpE5DczlOAu+22BMJdpagGYZYVBhtmPRCl+T9pB4wOkvfCuK0T5yaCWf3n31faeUHtdRnHQQcygnd+Eg/ymrwhbahHl2OldyDAWQbNZ9uPKPXWIwfj+zHVg8z7chUpPfg2cRxT56czGQX9gvtwhszbYUQejkuJ3xS7S1SJPhR0= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by mail-ed1-x531.google.com with SMTP id 4fb4d7f45d1cf-5bf01bdaff0so3734710a12.3 for ; Wed, 21 Aug 2024 10:57:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=baylibre-com.20230601.gappssmtp.com; s=20230601; t=1724263050; x=1724867850; darn=gcc.gnu.org; h=subject:from:to:content-language:user-agent:mime-version:date :message-id:from:to:cc:subject:date:message-id:reply-to; bh=dYJAcaWlxAlKp6Us2YB44O2DKeZQi1Xrm27tBq2fSyA=; b=p9jFK4baNHP9VGY3xpipLvpw9Ipxj73pnApFpcvccLpck2nFzgb1EYJTuvEP+WB4+g v9HQfeOd1SGZL1wN9/qL0opBwrTunjyVEMdTlllX2L1/2wLlWmzfqrqyuADhugOSXNLv IP6yJexfair7gSb3KrYp8VwkyIl9kynRcjQ4Avmn9raoHnrNNgGyfDwBsiChU5ai+gyU Mi597gkbEkX9pEhqxqDkh24clSMitUa5fwkwwpGU7QQKA3zbbkab5w09vv/zen8M9vcL BcrY5hgoYrDMbGGLXa7l4pomoqW1Bn6oFMClYRn7V3mIYbZOR2f1ipkN+oTlsv+7tXig ayzw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1724263050; x=1724867850; h=subject:from:to:content-language:user-agent:mime-version:date :message-id:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=dYJAcaWlxAlKp6Us2YB44O2DKeZQi1Xrm27tBq2fSyA=; b=VDAqQD4AgDkZNewHfTt426IMgWlDpIKe6x6XiUdaPEYxzqaZvsWBydY0JwDR1Lxoge x6UIc9+Bhk+Hsy7vNONe4Yvm/Y9RhP9BQFfbb7XS50yRhEKQ8ZpPD0EWHZp8Rikiu8hv MDWwAXwJTaiZ+R/hVVxKaMNwt1NDcQxnOuaqOE58J/+xmMiyM+v4US8dC5SysydqCufz AsMyzt0VDngELKdKz8ySSl9rQ6WckLT6Z2iCLrT4IrYVVPD/A7ZpWRzS+5/7BTbLwlk0 4I+YwIarBqAtw6XTAecc3L0qITzN7qSsPXcXnzyTfVHjshXiIkc1AK94c6vgERIPJGwb rrGg== X-Gm-Message-State: AOJu0YxrZ4ZaQEhoyY3604M4IzNp8dU4pd+Q7730UZhR6iqWsd8WrddV RD6RsnUbDENQsWEZwhNudEJM1nj/BLmmQP2MizbyyiUe7qjb7XH5GRkfTeYvgiTS9CM0/pnPjGY V X-Google-Smtp-Source: AGHT+IF5wkW0kvjjt92Xb4/LzFhQH8iD0wY8FdDWPJjUQGtjqFQcI/nahWbxPBjn2TZ9XqXz1pedPQ== X-Received: by 2002:a17:907:7216:b0:a7d:a29e:5c33 with SMTP id a640c23a62f3a-a866f3564a3mr217117766b.28.1724263049999; Wed, 21 Aug 2024 10:57:29 -0700 (PDT) Received: from ?IPV6:2001:16b8:26ed:d400:9b8c:cae6:ae2f:e89? (200116b826edd4009b8ccae6ae2f0e89.dip.versatel-1u1.de. [2001:16b8:26ed:d400:9b8c:cae6:ae2f:e89]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-a8685d4d333sm36583566b.155.2024.08.21.10.57.28 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 21 Aug 2024 10:57:29 -0700 (PDT) Message-ID: <30736961-4346-450b-a86c-e3794db20948@baylibre.com> Date: Wed, 21 Aug 2024 19:57:27 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gcc-patches , Jakub Jelinek , Sandra Loosemore From: Tobias Burnus Subject: [patch] libgomp.texi: Document OpenMP's Interoperability Routines X-Spam-Status: No, score=-11.9 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, GIT_PATCH_0, KAM_SHORT, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gcc-patches-bounces~incoming=patchwork.ozlabs.org@gcc.gnu.org Add documentation for OpenMP's interoperability routines. This obviously, depends on the actual implementation patch, posted at: https://gcc.gnu.org/pipermail/gcc-patches/2024-August/661035.html (albeit I will post a v2 in a moment). I am sure there will be comments, suggestions and remarks :-) Tobias PS: I am not 100% sure whether adding the implementation detail makes sense or not. libgomp.texi: Document OpenMP's Interoperability Routines libgomp/ChangeLog: * libgomp.texi (Interoperability Routines): Add. diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index fe25d879788..ecc60882d72 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -656,7 +656,7 @@ specification in version 5.2. * Lock Routines:: * Timing Routines:: * Event Routine:: -@c * Interoperability Routines:: +* Interoperability Routines:: * Memory Management Routines:: @c * Tool Control Routine:: * Environment Display Routine:: @@ -2884,21 +2884,294 @@ event handle that has already been fulfilled is also undefined. -@c @node Interoperability Routines -@c @section Interoperability Routines -@c -@c Routines to obtain properties from an @code{omp_interop_t} object. -@c They have C linkage and do not throw exceptions. -@c -@c @menu -@c * omp_get_num_interop_properties:: -@c * omp_get_interop_int:: -@c * omp_get_interop_ptr:: -@c * omp_get_interop_str:: -@c * omp_get_interop_name:: -@c * omp_get_interop_type_desc:: -@c * omp_get_interop_rc_desc:: -@c @end menu +@node Interoperability Routines +@section Interoperability Routines + +Routines to obtain properties from an object of OpenMP interop type. +They have C linkage and do not throw exceptions. + +@menu +* omp_get_num_interop_properties:: Get the number of implementation-specific properties +* omp_get_interop_int:: Obtain integer-valued interoperability property +* omp_get_interop_ptr:: Obtain pointer-valued interoperability property +* omp_get_interop_str:: Obtain string-valued interoperability property +* omp_get_interop_name:: Obtain the name of an interop_property value as string +* omp_get_interop_type_desc:: Obtain type and description to an interop_property +* omp_get_interop_rc_desc:: Obtain error string to an interop_rc error code +@end menu + + + +@node omp_get_num_interop_properties +@subsection @code{omp_get_num_interop_properties} -- Get the number of implementation-specific properties +@table @asis +@item @emph{Description}: +The @code{omp_get_num_interop_properties} function returns the number of +implementation-defined interoperability properties available for the passed +@var{interop}, extending the OpenMP-defined properties. The available OpenMP +interop_property-type values range from @code{omp_ipr_first} to the value +returned by @code{omp_get_num_interop_properties} minus one. + +No implementation-defined properties are currently defined in GCC. + +Implementation remark: In GCC, the Fortran interface differs from the one shown +below: the function has C binding, @var{interop} is passed by value and an +integer of @code{c_int} kind is returnd, permitting to have the same ABI as the +C function. This does not affect the usage of the function when GCC's +@code{omp_lib} module or @code{omp_lib.h} header is used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{int omp_get_num_interop_properties(const omp_interop_t interop)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer function omp_get_num_interop_properties(interop)} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@end multitable + +@item @emph{See also}: +@ref{omp_get_interop_name}, @ref{omp_get_interop_type_desc} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.1, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.1 +@end table + + + +@node omp_get_interop_int +@subsection @code{omp_get_interop_int} -- Obtain integer-valued interoperability property +@table @asis +@item @emph{Description}: +The @code{omp_get_interop_int} function returns the integer value associated +with the @var{property_id} interoperability property of the passed @var{interop} +object. If successful, @var{ret_code} is set to @code{omp_irc_success}. + +Implementation remark: In GCC, the Fortran interface differs from the one shown +below: the function has C binding and @var{interop} and @var{property_id} are +passed by value, permitting to have the same ABI as the C function. This does +not affect the usage of the function when GCC's @code{omp_lib} module or +@code{omp_lib.h} header is used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{omp_intptr_t omp_get_interop_int(const omp_interop_t interop, + omp_interop_property_t property_id, int *ret_code)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer(c_intptr_t) function omp_get_interop_int(interop, + property_id, ret_code)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_intptr_t} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@item @tab @code{integer(omp_interop_property_kind) property_id} +@item @tab @code{integer(omp_interop_rc_kind), intent(out) :: ret_code} +@end multitable + +@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} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.2, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.2 +@end table + + + +@node omp_get_interop_ptr +@subsection @code{omp_get_interop_ptr} -- Obtain pointer-valued interoperability property +@table @asis +@item @emph{Description}: +The @code{omp_get_interop_int} function returns the pointer value associated with +the @var{property_id} interoperability property of the passed @var{interop} +object. If successful, @var{ret_code} is set to @code{omp_irc_success}. + +Implementation remark: In GCC, the Fortran interface differs from the one shown +below: the function has C binding and @var{interop} and @var{property_id} are +passed by value, permitting to have the same ABI as the C function. This does +not affect the usage of the function when GCC's @code{omp_lib} module or +@code{omp_lib.h} header is used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void *omp_get_interop_ptr(const omp_interop_t interop, + omp_interop_property_t property_id, int *ret_code)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_get_interop_int(interop, + property_id, ret_code)} +@item @tab @code{use, intrinsic :: iso_c_binding, only : c_ptr} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@item @tab @code{integer(omp_interop_property_kind) property_id} +@item @tab @code{integer(omp_interop_rc_kind), intent(out) :: ret_code} +@end multitable + +@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} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.3, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.3 +@end table + + + +@node omp_get_interop_str +@subsection @code{omp_get_interop_str} -- Obtain string-valued interoperability property +@table @asis +@item @emph{Description}: +The @code{omp_get_interop_str} function returns the string value associated with +the @var{property_id} interoperability property of the passed @var{interop} +object. If successful, @var{ret_code} is set to @code{omp_irc_success}. + +Implementation remark: In GCC, the Fortran interface differs from the one shown +below: @var{interop} and @var{property_id} are passed by value. This does not +affect the usage of the function when GCC's @code{omp_lib} module or +@code{omp_lib.h} header is used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{const char *omp_get_interop_str(const omp_interop_t interop, + omp_interop_property_t property_id, int *ret_code)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{character(:) function omp_get_interop_str(interop, + property_id, ret_code)} +@item @tab @code{pointer :: omp_get_interop_str} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@item @tab @code{integer(omp_interop_property_kind) property_id} +@item @tab @code{integer(omp_interop_rc_kind), intent(out) :: ret_code} +@end multitable + +@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} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.4, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.4 +@end table + + + +@node omp_get_interop_name +@subsection @code{omp_get_interop_name} -- Obtain the name of an @code{interop_property} value as string +@table @asis +@item @emph{Description}: +The @code{omp_get_interop_name} function returns the name of the property +itself as string; for the properties specified by the OpenMP specification, +the name matches the name of the named constant with the @code{omp_ipr_} +prefix removed. + +Implementation remark: In GCC, the Fortran interface differs from the one shown +below: @var{interop} and @var{property_id} are passed by value. This does not +affect the usage of the function when GCC's @code{omp_lib} module or +@code{omp_lib.h} header is used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{const char *omp_get_interop_name(const omp_interop_t interop, + omp_interop_property_t property_id)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{character(:) function omp_get_interop_name(interop, + property_id)} +@item @tab @code{pointer :: omp_get_interop_name} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@item @tab @code{integer(omp_interop_property_kind) property_id} +@end multitable + +@item @emph{See also}: +@ref{omp_get_num_interop_properties}, @ref{omp_get_interop_type_desc} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.5, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.5 +@end table + + + +@node omp_get_interop_type_desc +@subsection @code{omp_get_interop_type_desc} -- Obtain type and description to an @code{interop_property} +@table @asis +@item @emph{Description}: +The @code{omp_get_interop_type_desc} function returns a string that describes in +human-readable form the data type associated with the @var{property_id} +interoperability property of the passed @var{interop} object. + +Implementation remark: In GCC, the Fortran interface differs from the one shown +below: @var{interop} and @var{property_id} are passed by value. This does not +affect the usage of the function when GCC's @code{omp_lib} module or +@code{omp_lib.h} header is used. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{const char *omp_get_interop_type_desc(const omp_interop_t interop, + omp_interop_property_t property_id)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{character(:) function omp_get_interop_type_desc(interop, + property_id)} +@item @tab @code{pointer :: omp_get_interop_type_desc} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@item @tab @code{integer(omp_interop_property_kind) property_id} +@end multitable + +@item @emph{See also}: +@ref{omp_get_num_interop_properties}, @ref{omp_get_interop_name} +@c @ref{Offload-Target Specifics} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.6, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.6 +@end table + + + +@node omp_get_interop_rc_desc +@subsection @code{omp_get_interop_rc_desc} -- Obtain error string to an @code{interop_rc} error code +@table @asis +@item @emph{Description}: +The @code{omp_get_interop_rc_desc} function returns a string value describing +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}. + +@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, + omp_interop_rc_t ret_code)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{character(:) function omp_get_interop_rc_desc(interop, + property_id, ret_code)} +@item @tab @code{pointer :: omp_get_interop_rc_desc} +@item @tab @code{integer(omp_interop_kind), intent(in) :: interop} +@item @tab @code{integer (omp_interop_rc_kind) ret_code} +@end multitable + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.12.7, +@uref{https://www.openmp.org, OpenMP specification TR13}, Section 26.7 +@end table + + @node Memory Management Routines @section Memory Management Routines