From patchwork Wed Jan 3 18:31:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 184817 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:6f82:b0:100:9c79:88ff with SMTP id tb2csp5192545dyb; Wed, 3 Jan 2024 10:32:27 -0800 (PST) X-Google-Smtp-Source: AGHT+IFxAWUXHfHxi1sFdjpG5HpmN4S0cFZOI00mffQuQf1nBuyOBl4VUa92KDcjzhAH0onHLv6W X-Received: by 2002:a05:620a:29c1:b0:781:5dd7:fd5b with SMTP id s1-20020a05620a29c100b007815dd7fd5bmr14593110qkp.77.1704306746832; Wed, 03 Jan 2024 10:32:26 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1704306746; cv=pass; d=google.com; s=arc-20160816; b=TIvZyxxn6vKYfRuaBoMendqwYVni9fBc11PTi/mi9Pg++rHGv3F1dMNQ4kNX3Qt3C0 ST4g9QYYZjKXyYoWX8AgC2ktlV1emWfP6HfBzo30YpV4VWFz8RwbJ5+XQUCpTU2a2Pn2 8xhzUa4wyHi9/+BHiLrAHIdmA2WFPrOvHNmvG6HB27Fyu20HnzXYv+omwEEV4fGfqOqu 3iGv2fWCLDy6zzryFeXzbmX3rO49WdZNZ0lfE+wsqQ3cpbDH1kvdalSRcwLjGw4apAXD knDImWqpDXCglerjSdu2d68Tu6/S/APyTwl0pRbXT/09jL+B7pDBAweDMiA+1XQ7uWVx xO0A== ARC-Message-Signature: i=2; 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:cc:to :content-language:user-agent:mime-version:date:message-id :ironport-sdr:arc-filter:dmarc-filter:delivered-to; bh=5PUm21DjgNcEL7XXkciTMi4nnZLi8YHVxkkJvIuOZjU=; fh=K6KS221asrbXGgpvhu0/y1lNDAw9QJrz77IALe5/vJ4=; b=sxV4aK/KQrUlQbSXQ6e2NraQfFS9DoWm6J9YTKJ6t5hpFDu2USix5lK/bmFiTe2jYC mv0C2iWNxgz8IUswAstLc8Aqhe7ByLQH6o3IxcGEQFMFeXRnzTAbisQdtiW2ESnAlaKw wNnXPoasLWUD0nOsyqv99OgpqUcnhjqlKwEln3/6WwD1axM2HzckqSpPAzBSTKS3TtVI 1oaxavujatSVJBBv69sijxLQjl18N0uhm73DgA9dUpsgnODZyV0xSeKd1lxJFI93WFrM aSpNbsIj4X5/QhVmohox7b9N/6S7FDtPSpXxcdibZHVDcSBDc5SesA1kmYOEhxCPY68f 7rJg== ARC-Authentication-Results: i=2; mx.google.com; arc=pass (i=1); 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 w13-20020a05620a424d00b007818450b895si13548861qko.393.2024.01.03.10.32.26 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 03 Jan 2024 10:32:26 -0800 (PST) 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; arc=pass (i=1); 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 8A472385801F for ; Wed, 3 Jan 2024 18:32:26 +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 1B4A03858C62 for ; Wed, 3 Jan 2024 18:31:37 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 1B4A03858C62 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 1B4A03858C62 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=1704306699; cv=none; b=uansjwfnv5Pchl/UrgxOpBLEFWJJRBA4u2qR5onpCxI2mQcYRxKhR8Q71cyGA3uEKd3/aecpsEnNvEAyt8RC7W0LOIOvCX+Qj3eNGGDiSxtT40baXEXIHxJWJ5Ppsc0Y9zUCJ92/RYCe467IxJZQFNOChoDRLJhJGtjpXRk+iSk= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1704306699; c=relaxed/simple; bh=ULBxMbZcgMc+ZsfE1NhEDmPK4LIZnNvClzM1QGD3NOM=; h=Message-ID:Date:MIME-Version:To:From:Subject; b=S35Rn2vBCh060lWtne9sNQpkb7xGJhe0jVdEeVge9Mnv+satxCbCsQJrzdkYCVbXUIzXcwyYeOqusbEeIKtmJQmEDTPV3yzIYoZ1+luNj6+HbP53R7Ormd/iWce0nLzPHTdm64fITtNMcrg5Ai6AWT25psRXYU3W1qKBxSq5NOA= ARC-Authentication-Results: i=1; server2.sourceware.org X-CSE-ConnectionGUID: zFSxQFvhQSaEaW7PQQaBpw== X-CSE-MsgGUID: 2E3SO+NLSK2B0LBj5Ruymg== X-IronPort-AV: E=Sophos;i="6.04,328,1695715200"; d="diff'?scan'208";a="26921835" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa4.mentor.iphmx.com with ESMTP; 03 Jan 2024 10:31:35 -0800 IronPort-SDR: dKx/m4Jd/0ZnvUGStKK4iPz6g56b7VHUBCI9guBfPWBxJh4GGDKEBnzPrIt4obqJIZKfnQRwi6 QYOaLXuU5d5xyG9j1P2ajEc25KK2Ud+ffhYIoIYwpNdhDW2ZOaq4fKuUlL1APtxLlqtiPJfV+F LfZ01PQa2QIh4OmGZAkrr+rHAWBTsQAJIA+7HNYgrJWbT+w2iu53VgJO0m+0wJUPPoW/I37rk9 +L3QkNh1qIW9POFT8SvlLpsoSQjSwQ/gRglkuJb8MNzj2ieMT4eQSDyc9uYPAEZV2RB0vD5top DxM= Message-ID: <7280b435-a7ee-4df5-b7ea-011ae17993d7@codesourcery.com> Date: Wed, 3 Jan 2024 19:31:25 +0100 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gcc-patches CC: Jakub Jelinek , Sandra Loosemore From: Tobias Burnus Subject: [patch] libgomp.texi: Document omp_display_env X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-11.mgc.mentorg.com (139.181.222.11) 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+ouuuleilei=gmail.com@gcc.gnu.org X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1787095151062590182 X-GMAIL-MSGID: 1787095151062590182 Another small step in my side project of documenting all OpenMP routines in libgomp.texi Here, only 'omp_display_env' is added. (New since OpenMP 5.1 but since a long time in GCC, some fineprint in both the implementation and in the documentation is based on TR11.) * * * RFC - regarding printing the values (env.c not the documentation): I am wondering whether to change "OMP_VAR = 'val'" to "OMP_VAR='val'", i.e. to remove the spaces around the equal sign. Pro: The latter is friendlier when using the env var with POSIX shells / Bash as those do not permit spaces. (While 'setenv' in the cshell requires a space instead of an equal size.) Since OpenMP has the '[device] ' prevfix which is used by many implementations, including GCC, copy'n'paste is now harder and the benefit of removing the space is lower. Additionally, the OpenMP document has "format NAME ’=’ VALUE" which also implies no spaces and LLVM's runtime library also prints it without spaces. Thoughts? (The attached patch documents the current implementation.) * * * Comments or suggestions to the .texi patch itself? 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 libgomp/ChangeLog: * libgomp.texi (Environment Display Routine): Uncomment and add omp_display_env description. (OMP_DISPLAY_ENV): Update wording, add 'see also'. libgomp/libgomp.texi | 109 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 94 insertions(+), 15 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index c727850397d..9999686f712 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -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 @@ -2919,18 +2919,93 @@ 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 number and the initial value of ICVs. +It has C linkage and do 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 GCC version number and initial value of +internal control variables (ICVs) is shown on @code{stderr}. Initial value +denotes the value at startup after evaluating the environment variables, such +that later calls to API routines or clauses used in enclosing constructs do not +affect the @emph{displayed} values. + +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 name-value lines are +(usually and in GCC) indented by two spaces; the @var{name} is followed by an +equal sign and the @var{value} is enclosed in single quotes; in GCC, the equal +sign is preceded and followed by a single space. + +The first line has as @var{name} either (usually and in GCC) @samp{_OPENMP} or +@samp{openmp_version} and shows as value the 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 optionally (and in GCC +always) 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 +3257,16 @@ 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; GCC shows an error and continues +the execution. +@item @emph{See also}: +@ref{omp_display_env} @item @emph{Reference}: @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.12