From patchwork Wed Jun 14 10:34:20 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 107879 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp1140723vqr; Wed, 14 Jun 2023 03:35:02 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ4fTkVD3T6U+6rh64eddqH6+OPbXrlo7WBKZk01rpGchFM2nEP+Lu8u65czMpR0nUC4u/Fr X-Received: by 2002:a17:907:8a02:b0:973:8198:bbf7 with SMTP id sc2-20020a1709078a0200b009738198bbf7mr15394191ejc.11.1686738902384; Wed, 14 Jun 2023 03:35:02 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1686738902; cv=none; d=google.com; s=arc-20160816; b=F45S4vsnRSsEzNtLGAia03rg/oqLP2B3ZqAsT1OOKBedNC0jtlaaNPM9Q3v95oUwe2 Oz8lODchdXKqHnwSLUIw6C/3FXrti6riKg3T0IAGQzY9AnlO7A8kQqBQ4INQKO0z+8PT sl6HDaCoyxWUolP1PAtiWr4D0FlUUaOFyhGRoSqazAbve5wYSrnggzkxu1uSzASpsrBt nMRVrg1bpCrShBrLx80cmGZlKZN5gcJvNFNPfJ02dbdbem4KReHcrszzNDS1Majbg0Yl Oc+yD/xokYg2ZQ5OV39+Hw+JAKNAh51ZG8ZIdPVnSWDBECcTt04bUHG8IEkmV/El/D7P BmDw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender: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=DuaTMzxGZEmbtVA5JywWQgpzf5iP3mA7/t5gMFk9980=; b=l7L2o9t1qCQrtt5nIPXlKJqaqTCw2iFBPi0WlTaDWYTvRjHSFSKOgZP091yJiCi1rH 19npB3pJMCyACwTvra57abd3PzOQ51hOmi5tRmLW9LSek5Lsgn3K5QUKJlLpaMpMTetq wgOYuY9FVr1GDy+SjGBKLqYNS0ub4RuhRAycKkesDPXRMz5uvfYFiAX33U32OYNbv4Td bKTNEvb7EOFSxjA6muJjf8V+pseUp5Ls1vC6INe85kHEnye0O9fVHtitOBmk3hdRndSi ciFnCAEStzOp8IMAhUOtVRZET9zagLQBL4q7c7bFJYnMYCIj6Q3Myp4f1T8iRy/8MPpN 4D0A== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) smtp.mailfrom="gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org" Received: from sourceware.org (ip-8-43-85-97.sourceware.org. [8.43.85.97]) by mx.google.com with ESMTPS id gs22-20020a170906f19600b009745fc8b9bcsi7804906ejb.105.2023.06.14.03.35.02 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 14 Jun 2023 03:35:02 -0700 (PDT) Received-SPF: pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 as permitted sender) client-ip=8.43.85.97; Authentication-Results: mx.google.com; spf=pass (google.com: domain of gcc-patches-bounces+ouuuleilei=gmail.com@gcc.gnu.org designates 8.43.85.97 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 CE4173858289 for ; Wed, 14 Jun 2023 10:34:54 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa3.mentor.iphmx.com (esa3.mentor.iphmx.com [68.232.137.180]) by sourceware.org (Postfix) with ESMTPS id E69E93858D38 for ; Wed, 14 Jun 2023 10:34:28 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E69E93858D38 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-IronPort-AV: E=Sophos;i="6.00,242,1681200000"; d="diff'?scan'208";a="8749789" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa3.mentor.iphmx.com with ESMTP; 14 Jun 2023 02:34:25 -0800 IronPort-SDR: 6zSi70i9GusRpuYrpBoUchk3CZbBatz7Crb5DYvg/IzOPHPzdPq0zm+f316OKPNmDMDkaTqJBS U1uGmqYVOnM1lVbbsJzqKZg35kVlEcIUCbghKTa/3hlrSICVwV5y1fDRT9IsS77MjL8fLgJWuD zTBWNe3GYKEkFRm6g+DczBD7Qb4gi9cqUzxvWnMZ5tAS/qVAeNSUI/9aQZun1H0RXMAmpkexjS ffl2qco8nuxr0+gc/9irovcRRitO606JhS15CH6c76oI1U5XZNkhm5Cptmg8WaXVTn5IhjjqHC tdM= Message-ID: <641f281f-4ba2-0ab2-f52b-9e30fd200a14@codesourcery.com> Date: Wed, 14 Jun 2023 12:34:20 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.12.0 Content-Language: en-US To: gcc-patches , Sandra Loosemore , Jakub Jelinek From: Tobias Burnus Subject: [Patch] libgomp.texi: Document allocator + affininity env vars X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-12.mgc.mentorg.com (139.181.222.12) 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.29 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 Sender: "Gcc-patches" X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1768673931123976984?= X-GMAIL-MSGID: =?utf-8?q?1768673931123976984?= Comments on the wording and/or the content? I did notice that we missed to document three OMP_* environment variables, hence, I added them. (For OMP_ALLOCATOR, I expect an update once the 5.1 extensions have been implemented.) (Some cross references could be added if we had/once we have documented the respective omp_(get,set)_... I think we lack about half of the API functions.) 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 allocator + affininity env vars libgomp/ChangeLog: * libgomp.texi (OMP_ALLOCATOR, OMP_AFFINITY_FORMAT, OMP_DISPLAY_AFFINITY): New. diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 21d3582a665..70b090824bb 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -1937,7 +1937,10 @@ section 4 of the OpenMP specification in version 4.5, while those beginning with @env{GOMP_} are GNU extensions. @menu +* OMP_ALLOCATOR:: Set the default allocator +* OMP_AFFINITY_FORMAT:: Set the format string used for affinity display * OMP_CANCELLATION:: Set whether cancellation is activated +* OMP_DISPLAY_AFFINITY:: Display thread affinity information * OMP_DISPLAY_ENV:: Show OpenMP version and environment variables * OMP_DEFAULT_DEVICE:: Set the device used in target regions * OMP_DYNAMIC:: Dynamic adjustment of threads @@ -1962,6 +1965,87 @@ beginning with @env{GOMP_} are GNU extensions. @end menu +@node OMP_ALLOCATOR +@section @env{OMP_ALLOCATOR} -- Set the default allocator +@cindex Environment Variable +@table @asis +@item @emph{Description}: +Sets the default allocator that is used when no allocator has been specified +in the @code{allocate} or @code{allocator} clause or when +@code{omp_null_allocator} is used as allocator when invoking an OpenMP memory +routine. The value should be one of the predefined allocators. +If unset, @code{omp_default_mem_alloc} is used. + +@c @item @emph{See also}: + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.21 +@end table + + + +@node OMP_AFFINITY_FORMAT +@section @env{OMP_AFFINITY_FORMAT} -- Set the format string used for affinity display +@cindex Environment Variable +@table @asis +@item @emph{Description}: +Sets the format string used when displaying OpenMP thread affinity information. +Special values are output using @code{%} followed by an optional size +specification and then either the single-character field type or its long +name enclosed in curly braces; using @code{%%} will display a literal percent. +The size specification consists of an optional @code{0.} or @code{.} followed +by a positive integer, specifing the minimal width of the output. With +@code{0.} and numerical values, the output is padded with zeros on the left; +with @code{.}, the output is padded by spaces on the left; otherwise, the +output is padded by spaces on the right. If unset, the value is +``@code{level %L thread %i affinity %A}''. + +Supported field types are: + +@multitable @columnfractions .10 .25 .60 +@item t @tab team_num @tab value returned by @code{omp_get_team_num} +@item T @tab num_teams @tab value returned by @code{omp_get_num_teams} +@item L @tab nesting_level @tab value returned by @code{omp_get_level} +@item n @tab thread_num @tab value returned by @code{omp_get_thread_num} +@item N @tab num_threads @tab value returned by @code{omp_get_num_threads} +@item a @tab ancestor_tnum + @tab value returned by + @code{omp_get_ancestor_thread_num(omp_get_level()-1)} +@item H @tab host @tab name of the host that executes the thread +@item P @tab process_id @tab process identifier +@item i @tab native_thread_id @tab native thread identifier +@item A @tab thread_affinity + @tab comma separated list of integer values or ranges, representing the + processors on which a process might execute, subject to affinity + mechanisms +@end multitable + +For instance, after setting + +@smallexample +OMP_AFFINITY_FORMAT="%0.2a!%n!%.4L!%N;%.2t;%0.2T;%@{team_num@};%@{num_teams@};%A" +@end smallexample + +with either @code{OMP_DISPLAY_AFFINITY} being set or when calling +@code{omp_display_affinity} with @code{NULL} or an empty string, the program +might display the following: + +@smallexample +00!0! 1!4; 0;01;0;1;0-11 +00!3! 1!4; 0;01;0;1;0-11 +00!2! 1!4; 0;01;0;1;0-11 +00!1! 1!4; 0;01;0;1;0-11 +@end smallexample + +@item @emph{See also}: +@ref{OMP_DISPLAY_AFFINITY} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.14 +@end table + + + @node OMP_CANCELLATION @section @env{OMP_CANCELLATION} -- Set whether cancellation is activated @cindex Environment Variable @@ -1979,6 +2063,26 @@ if unset, cancellation is disabled and the @code{cancel} construct is ignored. +@node OMP_DISPLAY_AFFINITY +@section @env{OMP_DISPLAY_AFFINITY} -- Display thread affinity information +@cindex Environment Variable +@table @asis +@item @emph{Description}: +If set to @code{FALSE} or if unset, affinity displaying is disabled. +If set to @code{TRUE}, the runtime will display affinity information about +OpenMP threads in a parallel region upon entering the region and every time +any change occurs. + +@item @emph{See also}: +@ref{OMP_AFFINITY_FORMAT} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.13 +@end table + + + + @node OMP_DISPLAY_ENV @section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables @cindex Environment Variable