From patchwork Tue Mar 19 16:34:08 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 229134 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client CN "localhost", Issuer "www.qmailtoaster.com" (not verified)) by ozlabs.org (Postfix) with ESMTPS id 109482C00BF for ; Wed, 20 Mar 2013 03:34:30 +1100 (EST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:subject:content-type; q= dns; s=dkim1; b=KykSNk24sLaKyrJRjh+ts+kfDBsO0cxxbjjMUNk+KSeuKAVN coFWLHmKZ47a6DySMoKKPnQrCwKA4Du1Mep8t04E/hZtj9JEtQo3kCoRs+Fxj3Xa cAo1uvXqVaT9uKsuvpVLDseYKQbiv9DxkDMWSTwQ6dwjDcvdmbSQeGgmiTQ= DKIM-Signature: v=1; a=rsa-sha1; c=simple; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:subject:content-type; s= dkim1; bh=HOf1q/U4FfpmcKNOdEOarcgHaVg=; b=b+b/gY6ZUrVNRp5icqSeM7 87ypbN23wUcKs8jDZOblIRmOKcgLD2C3DTwZgtIG7UrpiTPbI0HlKBljMSXopr6V qMepRORPnjx/2DD0ACrFioW+xIUXW8ata8Bp8OSwcQ+mcy74xVY5LkM4+S70uQ8P dY4Q1tB8PMR775jgj2JdI= Received: (qmail 24429 invoked by alias); 19 Mar 2013 16:34:24 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 24416 invoked by uid 89); 19 Mar 2013 16:34:15 -0000 X-Spam-Sware-Status: No, score=-2.2 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from mx01.qsc.de (HELO mx01.qsc.de) (213.148.129.14) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Tue, 19 Mar 2013 16:34:11 +0000 Received: from archimedes.net-b.de (port-92-195-211-180.dynamic.qsc.de [92.195.211.180]) by mx01.qsc.de (Postfix) with ESMTP id 01C253CE20; Tue, 19 Mar 2013 17:34:08 +0100 (CET) Message-ID: <51489380.7010106@net-b.de> Date: Tue, 19 Mar 2013 17:34:08 +0100 From: Tobias Burnus User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130215 Thunderbird/17.0.3 MIME-Version: 1.0 To: gcc patches , Jakub Jelinek Subject: [gomp 4.0] libgomp.texi: Add OMP_DISPLAY_ENV and GOMP_SPINCOUNT This patch adds documentation for OMP_DISPLAY_ENV, which was added by previously submitted patch, and it documents GOMP_SPINCOUNT, which was added 2010-12-02 but not yet documented. Additionally, I have updated the section references to OpenMP 4.0 (but only for the environment section) and did some minor cleanups. Tested with make pdf and make info. OK for the branch - after it has been created? Tobias 2013-03-19 Tobias Burnus * libgomp.texi (Environment Variables): Minor cleanup, update section refs to OpenMP 4.0rc2. (OMP_DISPLAY_ENV, GOMP_SPINCOUNT): Document these environment variables. diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 40c3830..c54fb2f 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -1083,12 +1083,9 @@ guaranteed not to change during the execution of the program. @node Environment Variables @chapter Environment Variables -The variables @env{OMP_DYNAMIC}, @env{OMP_MAX_ACTIVE_LEVELS}, -@env{OMP_NESTED}, @env{OMP_NUM_THREADS}, @env{OMP_SCHEDULE}, -@env{OMP_STACKSIZE},@env{OMP_THREAD_LIMIT} and @env{OMP_WAIT_POLICY} -are defined by section 4 of the OpenMP specifications in version 3.1, -while @env{GOMP_CPU_AFFINITY} and @env{GOMP_STACKSIZE} are GNU -extensions. +The environment variables which beginning with @env{OMP_} are defined by +section 4 of the OpenMP specification in version 4.0, while those +beginning with @env{GOMP_} are GNU extensions. @menu * OMP_DYNAMIC:: Dynamic adjustment of threads @@ -1099,9 +1096,11 @@ extensions. * OMP_SCHEDULE:: How threads are scheduled * OMP_THREAD_LIMIT:: Set the maximum number of threads * OMP_WAIT_POLICY:: How waiting threads are handled +* OMP_DISPLAY_ENV:: Show OpenMP version and environment variables * OMP_PROC_BIND:: Whether theads may be moved between CPUs * GOMP_CPU_AFFINITY:: Bind threads to specific CPUs * GOMP_STACKSIZE:: Set default thread stack size +* GOMP_SPINCOUNT:: Set the busy-wait spin count @end menu @@ -1119,7 +1118,7 @@ disabled by default. @ref{omp_set_dynamic} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, section 4.3 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.3 @end table @@ -1137,7 +1136,7 @@ If undefined, the number of active levels is unlimited. @ref{omp_set_max_active_levels} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, section 4.8 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.9 @end table @@ -1157,7 +1156,7 @@ regions are disabled by default. @ref{omp_set_nested} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, section 4.5 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.6 @end table @@ -1177,7 +1176,7 @@ level. If undefined one thread per CPU is used. @ref{omp_set_num_threads} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, section 4.2 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.2 @end table @@ -1198,7 +1197,7 @@ dynamic scheduling and a chunk size of 1 is used. @ref{omp_set_schedule} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, sections 2.5.1 and 4.1 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, sections 2.7.1 and 4.1 @end table @@ -1218,7 +1217,7 @@ stack size is left unchanged. If undefined, the stack size is system dependent. @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, sections 4.6 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.7 @end table @@ -1237,7 +1236,7 @@ the number of threads is not limited. @ref{omp_get_thread_limit} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, section 4.9 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.10 @end table @@ -1250,10 +1249,14 @@ the number of threads is not limited. Specifies whether waiting threads should be active or passive. If the value is @code{PASSIVE}, waiting threads should not consume CPU power while waiting; while the value is @code{ACTIVE} specifies that -they should. +they should. If undefined, threads wait actively for a short time +before waiting passively. + +@item @emph{See also}: +@ref{GOMP_SPINCOUNT} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, sections 4.7 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.8 @end table @@ -1264,14 +1267,32 @@ they should. @table @asis @item @emph{Description}: Specifies whether threads may be moved between processors. If set to -@code{true}, OpenMP theads should not be moved, if set to @code{false} -they may be moved. +@code{TRUE}, OpenMP theads should not be moved, if set to @code{FALSE} +they may be moved. If undefined, threads may move between processors. @item @emph{See also}: @ref{GOMP_CPU_AFFINITY} @item @emph{Reference}: -@uref{http://www.openmp.org/, OpenMP specifications v3.1}, sections 4.4 +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.4 +@end table + + + +@node OMP_DISPLAY_ENV +@section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables +@cindex Environment Variable +@table @asis +@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 will not be shown. + + +@item @emph{Reference}: +@uref{http://www.openmp.org/, OpenMP specifications v4.0}, section 4.12 @end table @@ -1298,7 +1319,7 @@ Fortran, may be used to query the setting of the @code{GOMP_CPU_AFFINITY} environment variable. A defined CPU affinity on startup cannot be changed or disabled during the runtime of the application. -If this environment variable is omitted, the host system will handle the +If this environment variable is omitted, the host system will handle the assignment of threads to CPUs. @item @emph{See also}: @@ -1331,6 +1352,33 @@ GCC Patches Mailinglist} +@node GOMP_SPINCOUNT +@section @env{GOMP_SPINCOUNT} -- Set the busy-wait spin count +@cindex Environment Variable +@cindex Implementation specific setting +@table @asis +@item @emph{Description}: +Determines how long a threads waits actively with consuming CPU power +before waiting passively without consuming CPU power. The value may be +either @code{INFINITE}, @code{INFINITY} to always wait actively or an +integer which gives the number of spins of the busy-wait loop. The +integer may optionally be followed by the following suffixes acting +as multiplication factors: @code{k} (kilo, thousand), @code{M} (mega, +million), @code{G} (giga, billion), or @code{T} (tera, trillion). +If undefined, 0 is used when @env{OMP_WAIT_POLICY} is @code{PASSIVE}, +300,000 is used when @env{OMP_WAIT_POLICY} is undefined and +30 billion is used when @env{OMP_WAIT_POLICY} is @code{ACTIVE}. +If there are more OpenMP threads than available CPUs, 1000 and 100 +spins are used for @env{OMP_WAIT_POLICY} being @code{ACTIVE} or +undefined, respectively; unless the @env{GOMP_SPINCOUNT} is lower +or @env{OMP_WAIT_POLICY} is @code{PASSIVE}. + +@item @emph{See also}: +@ref{OMP_WAIT_POLICY} +@end table + + + @c --------------------------------------------------------------------- @c The libgomp ABI @c ---------------------------------------------------------------------