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: 152056 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:612c:2908:b0:403:3b70:6f57 with SMTP id ib8csp1359925vqb; Thu, 12 Oct 2023 09:37:35 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEh6EHUtwGD5ukaP439WHZDHbX+PGQi9sEq0HtCa8l7dsda9Kk8sv7s7kMb0bZ9MlJyMxTT X-Received: by 2002:a05:620a:218c:b0:770:f1e1:202a with SMTP id g12-20020a05620a218c00b00770f1e1202amr23027081qka.66.1697128655032; Thu, 12 Oct 2023 09:37:35 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1697128655; cv=none; d=google.com; s=arc-20160816; b=H+/uEKXokQHiWsv4+SlSa0vdj4m7In0f2eU+/3bkNrRQQoTGCU+xfiSgICajtWLmvj pa0VZWplAphXgys2cKrD76A8Ie9GLQ97h5Ec8E8TThJEaP0lNYvZ09zJ/lLgH+NH78BS iXMy/lHvwpIKJiP3pg4VvM2DvIarTJVWdhfDFFImhKdotWuT8MlyWjGg56B/2MrDjk/1 22U2igKjeKFnB7+rIEkCZMQB82jfQ4+RJG4CPTdN5FQvDCbGLPQZx32hCUl+ljUjgm2m 5d0xxSmBHDtbpkbZzVoC/kWo/K1CrROQEpjtGXIDqH97cNFaCFqZr70PhZIaQM1wP/Xx Czjg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:from:to :content-language:user-agent:mime-version:date:message-id :ironport-sdr:dmarc-filter:delivered-to; bh=j6INvz0zhvVUrHxiZJqhfMnYXuUq14HTpHUJRRNguBQ=; fh=qkNWUlRBZkew0ISI4uevDbSSAIG4eEcsJO0pUMvFaAo=; b=yI/PhXYJdL4wGVn2ii30vYL1ciuBASPD4ZAnQXq0sfyE1blBW5KMT4jHk2LVx3xdT/ jppQSR1aMrTCUjtDpbyZc8S7LGTNw8Sy/b/92E/jEt2HuQruc0pgDJfC2wV9SrzonFnq EzvV6hy4Xfw070XBeSyAXmc4a/SqgT8FcbfcGISyQmFjRr8nuFrCe0UoU1+NnK+vPJ+v /CRlpdARpQTrh/esvapxilyH/7Mp72taVizCXEdECKxd6BjBigkHKJof3UxpjVkPM6D+ NYRijqMTm/hztqmWrwai92cGleBeCgg8eTDA9fwgN8GuZCafwSs/8rLfR/USEc68OJbC TwIA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from server2.sourceware.org (server2.sourceware.org. [2620:52:3:1:0:246e:9693:128c]) by mx.google.com with ESMTPS id bq30-20020a05620a469e00b0076db6aaa20esi11730952qkb.508.2023.10.12.09.37.34 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 12 Oct 2023 09:37:35 -0700 (PDT) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) client-ip=2620:52:3:1:0:246e:9693:128c; Authentication-Results: mx.google.com; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 2620:52:3:1:0:246e:9693:128c as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C4ABC3856DD5 for ; Thu, 12 Oct 2023 16:37:34 +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+ouuuleilei=gmail.com@gcc.gnu.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1779568376699325320 X-GMAIL-MSGID: 1779568376699325320 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