From patchwork Fri Jul 14 11:20:42 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 1807738 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=) 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 (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4R2TZ15vLxz20bh for ; Fri, 14 Jul 2023 21:21:07 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 5AD283858C3A for ; Fri, 14 Jul 2023 11:21:05 +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 069C03858CD1 for ; Fri, 14 Jul 2023 11:20:52 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 069C03858CD1 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.01,205,1684828800"; d="diff'?scan'208";a="11844229" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa4.mentor.iphmx.com with ESMTP; 14 Jul 2023 03:20:46 -0800 IronPort-SDR: Ft7Gw21+zCjEabZSBuVFAXy6KYTpc7A6LcOb8quOUlJrz9JuR8IrrbNTqbs5yEOO5bFE6YkxRp 5ZK9Mj8JjONpX8w1c1ocXPTG3Vm0odgl5JVdwG0gs9rHUsaqUs4kmzr6EdejyyquE7hvAcJOIG kdMSm9MhYx8QumtDtv5xAHcv6YTnCyPoqsNCzgyp/KiHv7tddL20vTRUxSuXRLUtk9qmRtwXTO Tj517Z1xtd2vT5w7nFYdogFmmIo2YG7Ubz+k03GPfSWsLr6X8OYJXaiKjuSWX0GB+9K+2UsgLs /IU= Message-ID: Date: Fri, 14 Jul 2023 13:20:42 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.13.0 Content-Language: en-US To: gcc-patches From: Tobias Burnus Subject: [committed] libgomp.texi: Extend memory allocation documentation 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, 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+incoming=patchwork.ozlabs.org@gcc.gnu.org Sender: "Gcc-patches" When looking at the documentation, I found some more gaps and a missing cross ref between OMP_ALLOCATOR and the 'Memory allocation' section. Hence, I applied the attached patch as r14-2518-ga85a106c35c6d1 For more documentation tasks, see for instance: https://gcc.gnu.org/PR110364 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 commit a85a106c35c6d1d9fd40627e149501e5e854bcc3 Author: Tobias Burnus Date: Fri Jul 14 13:15:07 2023 +0200 libgomp.texi: Extend memory allocation documentation libgomp/ * libgomp.texi (OMP_ALLOCATOR): Document the default values for the traits. Add crossref to 'Memory allocation'. (Memory allocation): Refer to OMP_ALLOCATOR for the available traits and allocators/mem spaces; document the default value for the pool_size trait. --- libgomp/libgomp.texi | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index 1645cc0a2d3..639dd05eb7b 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -2005,7 +2005,7 @@ the @code{omp_set_default_allocator} API routine can be used to change value. @multitable @columnfractions .45 .45 -@headitem Predefined allocators @tab Predefined memory spaces +@headitem Predefined allocators @tab Associated predefined memory spaces @item omp_default_mem_alloc @tab omp_default_mem_space @item omp_large_cap_mem_alloc @tab omp_large_cap_mem_space @item omp_const_mem_alloc @tab omp_const_mem_space @@ -2016,22 +2016,40 @@ value. @item omp_thread_mem_alloc @tab -- @end multitable -@multitable @columnfractions .30 .60 -@headitem Trait @tab Allowed values +The predefined allocators use the default values for the traits, +as listed below. Except that the last three allocators have the +@code{access} trait set to @code{cgroup}, @code{pteam}, and +@code{thread}, respectively. + +@multitable @columnfractions .25 .40 .25 +@headitem Trait @tab Allowed values @tab Default value @item @code{sync_hint} @tab @code{contended}, @code{uncontended}, @code{serialized}, @code{private} + @tab @code{contended} @item @code{alignment} @tab Positive integer being a power of two + @tab 1 byte @item @code{access} @tab @code{all}, @code{cgroup}, @code{pteam}, @code{thread} + @tab @code{all} @item @code{pool_size} @tab Positive integer + @tab See @ref{Memory allocation} @item @code{fallback} @tab @code{default_mem_fb}, @code{null_fb}, @code{abort_fb}, @code{allocator_fb} + @tab See below @item @code{fb_data} @tab @emph{unsupported as it needs an allocator handle} + @tab (none) @item @code{pinned} @tab @code{true}, @code{false} + @tab @code{false} @item @code{partition} @tab @code{environment}, @code{nearest}, @code{blocked}, @code{interleaved} + @tab @code{environment} @end multitable +For the @code{fallback} trait, the default value is @code{null_fb} for the +@code{omp_default_mem_alloc} allocator and any allocator that is associated +with device memory; for all other other allocators, it is @code{default_mem_fb} +by default. + Examples: @smallexample OMP_ALLOCATOR=omp_high_bw_mem_alloc @@ -2039,7 +2057,8 @@ OMP_ALLOCATOR=omp_large_cap_mem_space OMP_ALLOCATR=omp_low_lat_mem_space:pinned=true,partition=nearest @end smallexample -@c @item @emph{See also}: +@item @emph{See also}: +@ref{Memory allocation} @item @emph{Reference}: @uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.21 @@ -4632,6 +4651,11 @@ smaller number. On non-host devices, the value of the @node Memory allocation @section Memory allocation +For the available predefined allocators and, as applicable, their associated +predefined memory spaces and for the available traits and their default values, +see @ref{OMP_ALLOCATOR}. Predefined allocators without an associated memory +space use the @code{omp_default_mem_space} memory space. + For the memory spaces, the following applies: @itemize @item @code{omp_default_mem_space} is supported @@ -4674,9 +4698,12 @@ current node; therefore, unless the memory placement policy has been overridden, the @code{partition} trait @code{environment} (the default) will be effectively a @code{nearest} allocation. -Additional notes: +Additional notes regarding the traits: @itemize @item The @code{pinned} trait is unsupported. +@item The default for the @code{pool_size} trait is no pool and for every + (re)allocation the associated library routine is called, which might + internally use a memory pool. @item For the @code{partition} trait, the partition part size will be the same as the requested size (i.e. @code{interleaved} or @code{blocked} has no effect), except for @code{interleaved} when the memkind library is