From patchwork Sun Jan 14 14:26:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 1886465 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 4TCd0C2h46z1yPf for ; Mon, 15 Jan 2024 01:27:37 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 246D13858D1E for ; Sun, 14 Jan 2024 14:27:34 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mout.kundenserver.de (mout.kundenserver.de [212.227.126.133]) by sourceware.org (Postfix) with ESMTPS id 81EA93858D1E for ; Sun, 14 Jan 2024 14:27:14 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 81EA93858D1E Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=net-b.de Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=net-b.de ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 81EA93858D1E Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=212.227.126.133 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705242437; cv=none; b=M9g4BAGdim7k4sFn/A2GeHFLAMvG9bLQs6B/aDvplVDOge2Q2fT204PQ3K94Dd2jOb2PJxE4Dbq6QeagIJB3MReZlKxbMCjDziDdItkIADunKd7k6z7gbQTTU+eDBpdhFFecSLJM+lCskZf84+ewIeP11Bkfhb5YVyE7h2e3lSM= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1705242437; c=relaxed/simple; bh=iwWTnkCB7c4RfU7pfD7bs1nB/T8C2gXCBTmYWHZK5J8=; h=Message-ID:Date:MIME-Version:To:From:Subject; b=OjyL3CbedCOLEg9thCB3spEbUFy04PkwM3F1jNeraMn8+9wepeMFJ2UtQjkmg1I+3cCmjPPwx3ioZOxI9ZO+V/d/3lmW3i/PMrpL2MZn32tsmCTo13mrLFYocHTP/GafZ/MCjt2EwqKLJb4HfWc6M3whVmKGN6MVjW00ZYWom1A= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from [10.47.0.114] ([89.207.171.149]) by mrelayeu.kundenserver.de (mreue012 [213.165.67.97]) with ESMTPSA (Nemesis) id 1Mrfgi-1qmMlo3hfo-00njXt; Sun, 14 Jan 2024 15:27:06 +0100 Message-ID: <98216ca7-6a10-4342-b510-1f362127f619@net-b.de> Date: Sun, 14 Jan 2024 15:26:59 +0100 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 omp_pause_resource{,_all} X-Provags-ID: V03:K1:QUTuT8EtroTcb7OLjgwd7lrxb/Mvyh4Deg6ZH/+QmjFWJFQPWNf ZjZJ2n+9btot8XNWyLrTMmFar4VT+WN2L+C2Gn0+UuApNqaJhidEEsR2/OL3SL25YKkyFmF aoeTHaRKS78Cl75P1eroHpv3MapJi4G11sui2M+cKxVV6y5mtnCq/7/rEjcTRf7D0sONzEX K6lrGLqNDdetwN38asBDw== UI-OutboundReport: notjunk:1;M01:P0:/WXby/dg1DI=;tNdMEVgn9H2gCODP8s393zaVROr rQmhmPuDKlhIJbKCjF3A9TeXCEMUQ9qQ+SwS9J7i4BEsYhBlNgvw8wi4Kxr8ieFrkZoAf9QTl Q7RfL24GFDqZtgSZPpyh1+9mNLnOpFPtcnIlPFz/rqOyTF00dqRmOC87ulscG/rLGGXoRiwRX JnnEreAwIDAl9El28HWlAvxVThY0dokrQYaiPFkuhOxBP5O3ihvK+qjBa5Lo1s8+qDiQgbVvj /6S0JVcsbgeRd0OkMISv1ztvUuEK6p3JlMzfNeqvivpXnTLgYUIUKSVPUUyqlECC8+KYfNDEh FNmYjA1ftVoL7pfp6YslkEQk+HIsw4axi879regIFFKwXL9gp1rL3CpgRfH9O5ZZF72N56hJ4 36lyEMdzUVsWQBC1k//wy10iXVbsmjIaDiw4VcB8vQ/zvUfHjn6A+FPFA0rODxHZEruOf28HN j5g8poa+qFrm8st4WtXMMC0MREMFXJ9WPEUex7p+h8rQbCs1i+AU2oPbOREpZTPTVjgrVnLND ItGoQM2pVFrtlbNevPvQS0259UM+i/ckuxG4UAJXp15a6MwdEWfqcz7/o7dUR3PN8oPAKPZoD N343Z9+s9lVuFaui2fAtLzHC1Lp69mrVnzn+DCbVuxTTakXZaulwzj1Flagav1pVaQJCf/ycL T5fAC5lTr7bJeg5b9pn0DDtdbCg+5eiU8UqN671HhuMy46vGVv+8DuHAd4sjpDzgfRsS9G1ow B4Tp+as2sR771dOR9pD1PSy+pG+PfwmJMXqWtk4zI03uaZ0CSW9qlcY80DrFlhZJK3wtYVsXn vDU2ko2Tof/3Uzt7tqT/WUPb6WotTg9q12NnxZzdl0fmpgdqFfKy//zkn0QWCFSYftrG7yBKO 744yiuSQ2uST9CA== X-Spam-Status: No, score=-11.1 required=5.0 tests=BAYES_00, GIT_PATCH_0, KAM_DMARC_STATUS, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, 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 This documents two more OpenMP (5.0) routines, omp_pause_resource and omp_pause_resource_all. Comments, remarks, suggestions - to the patch or the documentation in general? Tobias PS: When looking at it, I found an issue in the spec with regards to a new constant (post TR12, hence, not added here) and the missing unspecified behavior when invoked from within a target region; that's now tracked as OpenMP spec issue #3793. PPS: Still to be documented routines: omp_target_memcpy* and the places/affinity routines. (Plus OMPT, interop and TR11/TR12/... but those have to be implemented first.) libgomp.texi: Document omp_pause_resource{,_all} libgomp/ChangeLog: * libgomp.texi (Runtime Library Routines): Document omp_pause_resource and omp_pause_resource_all. libgomp/libgomp.texi | 82 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 71 insertions(+), 11 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 74d4ef34c43..4946dfe2c84 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -561,7 +561,7 @@ specification in version 5.2. * Thread Affinity Routines:: * Teams Region Routines:: * Tasking Routines:: -@c * Resource Relinquishing Routines:: +* Resource Relinquishing Routines:: * Device Information Routines:: * Device Memory Routines:: * Lock Routines:: @@ -1504,16 +1504,76 @@ and @code{false} represent their language-specific counterparts. -@c @node Resource Relinquishing Routines -@c @section Resource Relinquishing Routines -@c -@c Routines releasing resources used by the OpenMP runtime. -@c They have C linkage and do not throw exceptions. -@c -@c @menu -@c * omp_pause_resource:: -@c * omp_pause_resource_all:: -@c @end menu +@node Resource Relinquishing Routines +@section Resource Relinquishing Routines + +Routines releasing resources used by the OpenMP runtime. +They have C linkage and do not throw exceptions. + +@menu +* omp_pause_resource:: Release OpenMP ressouces on a device +* omp_pause_resource_all:: Release OpenMP ressouces on all devices +@end menu + + + +@node omp_pause_resource +@subsection @code{omp_pause_resource} -- Release OpenMP ressouces on a device +@table @asis +@item @emph{Description}: +Free resources used by OpenMP programm and runtime library on and for the +device specified by @var{device_num}; on success, zero is returned and non-zero +otherwise. + +The value of @var{device_num} must be valid device number. 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{int omp_pause_resource(omp_pause_resource_t kind, int device_num);} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer function omp_pause_resource(kind, device_num)} +@item @tab @code{integer (kind=omp_pause_resource_kind) kind} +@item @tab @code{integer device_num} +@end multitable + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.43. +@end table + + + +@node omp_pause_resource_all +@subsection @code{omp_pause_resource_all} -- Release OpenMP ressouces on all devices +@table @asis +@item @emph{Description}: +Free resources used by OpenMP programm and runtime library on all devices, including +the host. On success, zero is returned and non-zero otherwise. + +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{int omp_pause_resource(omp_pause_resource_t kind);} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer function omp_pause_resource(kind)} +@item @tab @code{integer (kind=omp_pause_resource_kind) kind} +@end multitable + +@item @emph{See also}: +@ref{omp_pause_resource} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 3.2.44. +@end table + + @node Device Information Routines @section Device Information Routines