From patchwork Fri Jan 5 18:55:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 1883098 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=8.43.85.97; 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 [8.43.85.97]) (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 4T6CNf2NtDz1yP4 for ; Sat, 6 Jan 2024 05:56:32 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 6CAD53858C54 for ; Fri, 5 Jan 2024 18:56:30 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa4.mentor.iphmx.com (esa4.mentor.iphmx.com [68.232.137.252]) by sourceware.org (Postfix) with ESMTPS id 2ACE43858D20 for ; Fri, 5 Jan 2024 18:56:04 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 2ACE43858D20 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 2ACE43858D20 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=68.232.137.252 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704480967; cv=none; b=JZ1dvKc0t1UTvj7XLWKFZvMBNUFqAzfJ/pMgMGNK3oL2EFLUOAoEMlBDb7dLS80Xkb5kaRXCD8MGToFeTuXjuRl+KJ+JnXpPkAoLXpiNFCExl3OmGpCWWwZPpylPv9GXt9QANmwdcGMH2lmhd4tUyIKQHQqDyDeeAKzfA4shu9E= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704480967; c=relaxed/simple; bh=O4FFWLs6qFY/hRLYAmUdX74wCW+uA3t7LYj9+vcZvoU=; h=Message-ID:Date:MIME-Version:Subject:To:From; b=r28HZ0JVRet12EmafDZaVptXBjF3QfBBqX+obRjLk6fqnF0O7osH/yN5qqc7OYxznlkjLph55CoY3gsbkVusYTPHUicxDTqDaRk2Hmd7cCX2wzFybzep9eTgQztXI0spahhgmLuSxIlpq6A4vHFbvY3hIu1OTnVclU8Kn1MhkbA= ARC-Authentication-Results: i=1; server2.sourceware.org X-CSE-ConnectionGUID: v1m/2ih4R0ye7GqO4fPjNg== X-CSE-MsgGUID: g9WDINLiR7S0AdpvCw00eA== X-IronPort-AV: E=Sophos;i="6.04,334,1695715200"; d="diff'?scan'208";a="27179871" Received: from orw-gwy-02-in.mentorg.com ([192.94.38.167]) by esa4.mentor.iphmx.com with ESMTP; 05 Jan 2024 10:56:01 -0800 IronPort-SDR: 1/FM2eblk7/FRz+SR9jbGT/mbZM+0FEvLSKKNcyLS3QmjLMH6j/WGpcZ6hcsHiNxsAV4EeO1mv GvklXoGIg53gs3FjUfC4D7uqoClQMZgfylTITbDSXHbt+Eml2OP/xrC10UswOOETZ5RMBybGx9 /CpzE9x2/0R2xjxNhieCNa5xr3mGKNHWzWyON3Uc3BaCrlHCwj2Y1O7QZB6bqEmoVbA4RFEV+7 QPwyPV16tfTEIxxgFu6MQoNDInjxwWNGDbTvEATZHQpjWh4nu92p8WssfIahCV6ORL/Y6lsEoE JXo= Message-ID: <0cb9d98b-04b3-447e-a83d-090fe6a23186@codesourcery.com> Date: Fri, 5 Jan 2024 19:55:56 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: [patch] omp_target_is_accessible (was: [patch] libgomp.texi: Document omp_display_env) Content-Language: en-US To: Sandra Loosemore , gcc-patches CC: Jakub Jelinek , Sandra Loosemore References: <7280b435-a7ee-4df5-b7ea-011ae17993d7@codesourcery.com> <00cfcd93-7abe-a32c-caa7-ca5505ef3db9@siemens.com> From: Tobias Burnus In-Reply-To: <00cfcd93-7abe-a32c-caa7-ca5505ef3db9@siemens.com> X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-13.mgc.mentorg.com (139.181.222.13) To svr-ies-mbx-12.mgc.mentorg.com (139.181.222.12) X-Spam-Status: No, score=-11.3 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_DMARC_STATUS, SPF_HELO_PASS, 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 Hi all, updated patch attached - which also fixes some additional issues and adds omp_target_is_accessible. On 03.01.24 23:35, Sandra Loosemore wrote: > On 1/3/24 11:31, Tobias Burnus wrote: [...] > I'm not sure about the usability issues, except I think it's generally > easier to change an undocumented interface. :-) I have now removed some details, which are not really needed and can be gathered from the example. That makes it easier to change things in the future and makes it more readable. BTW: I kept the ' -- '; if we want to change this to '---', it should be done globally for the whole file as the latter isn't used at all and the former all the time. >> +Routine to display the OpenMP number and the initial value of ICVs. > > I'm not sure what an "OpenMP number is". Below it says "GCC version > number" and "OpenMP version" OpenMP number is used in the OpenMP spec but it does not really make sense. "GCC version number" is bogus as it should be OpenMP's. There are actually two version numbers of the OpenMP spec, the "real" one everyone uses like 4.5 and an integer one like 201511 denoting the year and month (= November as Supercomputing Conf is in November). The latter value permits '>=' comparisons and is available both as preprocessor macro (_OPENMP) and as Fortran named constant (openmp_version). I am not sure how to distinguish 'version' from 'version' in words, but 'OpenMP version number' should be okayish for the 20yymm number. (I used 4.5 & 201511 above as that's the highest OpenMP version for which GCC claims full support; I hope that we can bump it to 5.0 or 5.1 during the GCC 15 development. For 5.0, only some existing features have to be merged - most prominently missing are metadirectives but also a few smaller features that do exist on the OG13 branch) > I'd rephrase this a bit: > > ...is printed on @code{stderr}. The displayed values are those at > startup > after evaluating the environment variables; later calls to API routines > or clauses used in enclosing constructs do not affect the output. Applied. Thanks for the suggestion! > This is the documentation for the GCC implementation, so it's not > necessary to say "in GCC" Based on the real-world use of more comprehensive documentation, I think it makes sense to distinguish between spec-based behavior and implementation choice. However, I removed some level of less important details, avoiding 'in GCC'. Tobias ----------------- Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955 libgomp.texi: Document omp_display_env + omp_target_is_accessible Additionally, it fixes a typo and changes the OpenMP 5.2 section references (18.8.x) to OpenMP 5.1 ones (3.8.x) matching the mentioned OpenMP number. libgomp/ChangeLog: * libgomp.texi (OpenMP Technical Report 12): Fix a typo. (Device Memory Routines): Fix OpenMP 5.1 spec refs; add omp_target_is_accessible. (Environment Display Routine): Uncomment and add omp_display_env description. (OMP_DISPLAY_ENV): Update wording, add 'see also'. libgomp/libgomp.texi | 169 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 145 insertions(+), 24 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index c727850397d..30f69ee412b 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -501,7 +501,7 @@ Technical Report (TR) 12 is the second preview for OpenMP 6.0. modifiers of the @code{init} clause @tab N @tab @item @code{interop} clause to @code{dispatch} @tab N @tab -@item @code{message} and @code{severity} calauses to @code{parallel} directive +@item @code{message} and @code{severity} clauses to @code{parallel} directive @tab N @tab @item @code{self} clause to @code{requires} directive @tab N @tab @item @code{no_openmp_constructs} assumptions clause @tab N @tab @@ -570,7 +570,7 @@ specification in version 5.2. @c * Interoperability Routines:: * Memory Management Routines:: @c * Tool Control Routine:: -@c * Environment Display Routine:: +* Environment Display Routine:: @end menu @@ -1719,7 +1719,7 @@ pointers on devices. They have C linkage and do not throw exceptions. * omp_target_alloc:: Allocate device memory * omp_target_free:: Free device memory * omp_target_is_present:: Check whether storage is mapped -@c * omp_target_is_accessible:: +* omp_target_is_accessible:: Check whether memory is device accessible @c * omp_target_memcpy:: @c * omp_target_memcpy_rect:: @c * omp_target_memcpy_async:: @@ -1768,7 +1768,7 @@ is not supported. @ref{omp_target_free}, @ref{omp_target_associate_ptr} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.1 +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.1 @end table @@ -1802,7 +1802,7 @@ is not supported. @ref{omp_target_alloc}, @ref{omp_target_disassociate_ptr} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.2 +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.2 @end table @@ -1813,7 +1813,7 @@ is not supported. @item @emph{Description}: This routine tests whether storage, identified by the host pointer @var{ptr} is mapped to the device specified by @var{device_num}. If so, it returns -@emph{true} and otherwise @emph{false}. +a nonzero value and otherwise zero. In GCC, this includes self mapping such that @code{omp_target_is_present} returns @emph{true} when @var{device_num} specifies the host or when the host @@ -1848,7 +1848,53 @@ is not supported. @ref{omp_target_associate_ptr} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.3 +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.3 +@end table + + + +@node omp_target_is_accessible +@subsection @code{omp_target_is_accessible} -- Check whether memory is device accessible +@table @asis +@item @emph{Description}: +This routine tests whether memory, starting at the address given by @var{ptr} +and extending @var{size} bytes, is accessibly on the device specified by +@var{device_num}. If so, it returns a nonzero value and otherwise zero. + +The address given by @var{ptr} is interpreted to be in the address space of +the device and @var{size} must be positive. + +Note that GCC's current implementation assumes that @var{ptr} is a valid host +pointer. Therefore, all addresses given by @var{ptr} are assumed to be +accessible on the initial device. And, to err on the safe side, this memory +is only available on a non-host device that can access all host memory +([uniform] shared memory access). + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{int omp_target_is_accessible(const void *ptr,} +@item @tab @code{ size_t size,} +@item @tab @code{ int device_num)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer(c_int) function omp_target_is_accessible(ptr, &} +@item @tab @code{ size, device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, c_int} +@item @tab @code{type(c_ptr), value :: ptr} +@item @tab @code{integer(c_size_t), value :: size} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_associate_ptr} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.4 @end table @@ -1911,7 +1957,7 @@ is not supported. @ref{omp_target_alloc} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.9 +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.9 @end table @@ -1957,7 +2003,7 @@ is not supported. @ref{omp_target_associate_ptr} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.10 +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.10 @end table @@ -1997,7 +2043,7 @@ is not supported. @ref{omp_target_associate_ptr} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.11 +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.8.11 @end table @@ -2919,18 +2965,90 @@ was already deallocated or when the used allocator has already been destroyed. @c @node Tool Control Routine +@c @section Tool Control Routine @c @c FIXME -@c @node Environment Display Routine -@c @section Environment Display Routine -@c -@c Routine to display the OpenMP number and the initial value of ICVs. -@c It has C linkage and do not throw exceptions. -@c -@c menu -@c * omp_display_env:: -@c end menu +@node Environment Display Routine +@section Environment Display Routine + +Routine to display the OpenMP version number and the initial value of ICVs. +It has C linkage and does not throw exceptions. + +@menu +* omp_display_env:: print the initial ICV values +@end menu + +@node omp_display_env +@subsection @code{omp_display_env} -- print the initial ICV values +@table @asis +@item @emph{Description}: +Each time this routine is invoked, the OpenMP version number and initial value +of internal control variables (ICVs) is printed on @code{stderr}. The displayed +values are those at startup after evaluating the environment variables; later +calls to API routines or clauses used in enclosing constructs do not affect +the output. + +If the @var{verbose} argument is @code{false}, only the OpenMP version and +standard OpenMP ICVs are shown; if it is @code{true}, additionally, the +GCC-specific ICVs are shown. + +The output consists of multiple lines and starts with +@samp{OPENMP DISPLAY ENVIRONMENT BEGIN} followed by the name-value lines and +ends with @samp{OPENMP DISPLAY ENVIRONMENT END}. The @var{name} is followed by +an equal sign and the @var{value} is enclosed in single quotes. + +The first line has as @var{name} either @samp{_OPENMP} or @samp{openmp_version} +and shows as value the supported OpenMP version number (4-digit year, 2-digit +month) of the implementation, matching the value of the @code{_OPENMP} macro +and, in Fortran, the named constant @code{openmp_version}. + +In each of the succeeding lines, the @var{name} matches the environment-variable +name of an ICV and shows its value. Those line are might be prefixed by pair of +brackets and a space, where the brackets enclose a comma-separated list of +devices to which the ICV-value combination applies to; the value can either be a +numeric device number or an abstract name denoting all devices (@code{all}), the +initial host device (@code{host}) or all devices but the host (@code{device}). +Note that the same ICV might be printed multiple times for multiple devices, +even if all have the same value. + +The effect when invoked from within a @code{target} region is unspecified. + +@item @emph{C/C++}: +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void omp_display_env(int verbose)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{subroutine omp_display_env(vebose)} +@item @tab @code{logical, intent(in) :: verbose} +@end multitable + +@item @emph{Example}: +Note that the GCC-specific ICVs, such as the shown @code{GOMP_SPINCOUNT}, +are only printed when @var{varbose} set to @code{true}. + +@smallexample +OPENMP DISPLAY ENVIRONMENT BEGIN + _OPENMP = '201511' + [host] OMP_DYNAMIC = 'FALSE' + [host] OMP_NESTED = 'FALSE' + [all] OMP_CANCELLATION = 'FALSE' + ... + [host] GOMP_SPINCOUNT = '300000' +OPENMP DISPLAY ENVIRONMENT END +@end smallexample + + +@item @emph{See also}: +@ref{OMP_DISPLAY_ENV}, @ref{Environment Variables}, +@ref{Implementation-defined ICV Initialization} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.15 +@end table + @c --------------------------------------------------------------------- @c OpenMP Environment Variables @@ -3182,12 +3300,15 @@ any change occurs. @item @emph{ICV:} none @item @emph{Scope:} not applicable @item @emph{Description}: -If set to @code{TRUE}, the OpenMP version number and the values -associated with the OpenMP environment variables are printed to @code{stderr}. -If set to @code{VERBOSE}, it additionally shows the value of the environment -variables which are GNU extensions. If undefined or set to @code{FALSE}, -this information is not shown. +If set to @code{TRUE}, the runtime displays the same information to +@code{stderr} as shown by the @code{omp_display_env} routine invoked with +@var{verbose} argument set to @code{false}. If set to @code{VERBOSE}, the same +information is shown as invoking the routine with @var{verbose} set to +@code{true}. If unset or set to @code{FALSE}, this information is not shown. +The result for any other value is unspecified. +@item @emph{See also}: +@ref{omp_display_env} @item @emph{Reference}: @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.12