From patchwork Thu Oct 12 16:37:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 1847694 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=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 4S5wKJ5fTkz23jX for ; Fri, 13 Oct 2023 03:37:24 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C07C53856241 for ; Thu, 12 Oct 2023 16:37:22 +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 E98F93858C3A for ; Thu, 12 Oct 2023 16:37:10 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E98F93858C3A Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=mentor.com X-CSE-ConnectionGUID: w64+J9AhRLC1+yhXMMrQOQ== X-CSE-MsgGUID: sE52kwX+S0ewkDWw9gbZHw== X-IronPort-AV: E=Sophos;i="6.03,219,1694764800"; d="diff'?scan'208";a="19282035" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa4.mentor.iphmx.com with ESMTP; 12 Oct 2023 08:37:05 -0800 IronPort-SDR: yn1ia5mKKJTngnmOgy9WYm5eGMCp9WMnZ9qAFBk/X/jZOl3xcZ+pPOwnk/cyAc2Lar00r6eE1j a7K3i9iK5YJO81JzgJQ4T02IUPfOyfCuv4tB+R0llKrEkUG3RN7We2VnbFW/A8/UeA7r5cVy89 e9BqFUenGlwlrISKN6kIZctKwkjrihtSvzH932cgJewdCaSaf29xqsW72u4jH0ZPmlVLpgf94+ Wpmbq5l+myf/kf1W/Z3B//nXIodpoqPZNHWrCroA4oPy2P4CgsLRQhkRBsNOsILRhOLMfWXvUW KbU= Message-ID: <2111df82-33ad-4165-8516-f9107de0fbf0@codesourcery.com> Date: Thu, 12 Oct 2023 18:37:00 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gcc-patches , Sandra Loosemore , Jakub Jelinek From: Tobias Burnus Subject: [Patch] libgomp.texi: Clarify OMP_TARGET_OFFLOAD=mandatory X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-10.mgc.mentorg.com (139.181.222.10) 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, KAM_SHORT, SPF_HELO_PASS, SPF_PASS, TXREP 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 I noticed that while OMP_DEFAULT_DEVICE was updated a ref to OMP_TARGET_OFFLOAD (→ mandatory case) was missing. And OMP_TARGET_OFFLOAD wasn't updated at all for those changes. I hope the new version is clearer. Current versions: https://gcc.gnu.org/onlinedocs/libgomp/OMP_005fDEFAULT_005fDEVICE.html https://gcc.gnu.org/onlinedocs/libgomp/OMP_005fTARGET_005fOFFLOAD.html I have changed the reference to OpenMP 5.2 (from 4.5 and 5.0) as only the latter fully describes the current behavior; I first left in the current specification references and only added the v5.2 one, but I then did not see an advantage of doing so. Any comments or suggestions before I commit the attached patch? 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: Clarify OMP_TARGET_OFFLOAD=mandatory In OpenMP 5.0/5.1, the semantic of OMP_TARGET_OFFLOAD=mandatory was insufficiently specified; 5.2 clarified this with extensions/clarifications (omp_initial_device, omp_invalid_device, "conforming device number"). GCC's implementation matches OpenMP 5.2. libgomp/ChangeLog: * libgomp.texi (OMP_DEFAULT_DEVICE): Update spec ref; add @ref to OMP_TARGET_OFFLOAD. (OMP_TARGET_OFFLOAD): Update spec ref; add @ref to OMP_DEFAULT_DEVICE; clarify MANDATORY behavior. diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index ba8e9013814..46c4dcf90f1 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -2831,9 +2831,10 @@ device number 0 will be used. @item @emph{See also}: @ref{omp_get_default_device}, @ref{omp_set_default_device}, +@ref{OMP_TARGET_OFFLOAD} @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.13 +@uref{https://www.openmp.org, OpenMP specification v5.2}, Section 21.2.7 @end table @@ -3133,15 +3134,25 @@ variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED} or @code{DEFAULT}. If set to @code{MANDATORY}, the program will terminate with an error if -the offload device is not present or is not supported. If set to -@code{DISABLED}, then offloading is disabled and all code will run on the -host. If set to @code{DEFAULT}, the program will try offloading to the +any device construct or device memory routine uses a device that is unavailable +or not supported by the implementation, or uses a non-conforming device number. +If set to @code{DISABLED}, then offloading is disabled and all code will run on +the host. If set to @code{DEFAULT}, the program will try offloading to the device first, then fall back to running code on the host if it cannot. If undefined, then the program will behave as if @code{DEFAULT} was set. +Note: Even with @code{MANDATORY}, there will be no run-time termination when +the device number in a @code{device} clause or argument to a device memory +routine is for host, which includes using the device number in the +@var{default-device-var} ICV. However, the initial value of +the @var{default-device-var} ICV is affected by @code{MANDATORY}. + +@item @emph{See also}: +@ref{OMP_DEFAULT_DEVICE} + @item @emph{Reference}: -@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.17 +@uref{https://www.openmp.org, OpenMP specification v5.2}, Section 21.2.8 @end table