From patchwork Thu Oct 5 17:34:03 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 1844087 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 4S1dwW11gdz1yqD for ; Fri, 6 Oct 2023 04:34:33 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 65ADA385B515 for ; Thu, 5 Oct 2023 17:34:31 +0000 (GMT) X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from esa1.mentor.iphmx.com (esa1.mentor.iphmx.com [68.232.129.153]) by sourceware.org (Postfix) with ESMTPS id E1E473858CDB for ; Thu, 5 Oct 2023 17:34:09 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E1E473858CDB 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-CSE-ConnectionGUID: zHg+wL9vTY29ZA/opmwgGg== X-CSE-MsgGUID: cmlOtCT4T2ujoAVa78pqzw== X-IronPort-AV: E=Sophos;i="6.03,203,1694764800"; d="diff'?scan'208";a="21085091" Received: from orw-gwy-01-in.mentorg.com ([192.94.38.165]) by esa1.mentor.iphmx.com with ESMTP; 05 Oct 2023 09:34:08 -0800 IronPort-SDR: 1D1vnDpZbRVo6CnF73/GgwJHbLjF3ev7jzuzKSwQDLduCjMH97oxfFkQ1C4BANT5V1KXtwKvpv fioKbNMKtQOo+2I3d/kbX9UYRzl5IXFo0PCjjzCBfTRUUiAPzT0FvdCvrL14SYyMUcDktxDXDB akBedYT9iiNvIxWkZmucdAAbc+VFsaNoPpp3fTqWa52RcJ2tT2/7/15ihKjp8OaP1Bsh03Kcub y1I3rml+r3T3b4XxHG6WDbEBPA+eBgJQFyhh84Q9CbrwzlZ7h/xZgPzR1Uk9t++6tCpYGrGCZJ Sf0= Message-ID: <024726cc-ab05-4d3b-941f-1312d2d566d3@codesourcery.com> Date: Thu, 5 Oct 2023 19:34:03 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gcc-patches , Jakub Jelinek From: Tobias Burnus Subject: [Patch] libgomp.texi: Document some of the device-memory routines X-Originating-IP: [137.202.0.90] X-ClientProxiedBy: svr-ies-mbx-14.mgc.mentorg.com (139.181.222.14) 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 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 I was checking one of those functions - and now ended up documenting some of them. Still to be documented are omp_target_{is_accessible,memcpy*}. I did run into some possibly questionable code for corner cases and have filed https://gcc.gnu.org/PR111707 for those. The documentation matches the current implementation. Comments, suggestions, remarks? 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 some of the device-memory routines libgomp/ChangeLog: * libgomp.texi (Device Memory Routines): New. diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi index d24f590fd84..0d965f96d48 100644 --- a/libgomp/libgomp.texi +++ b/libgomp/libgomp.texi @@ -514,7 +514,7 @@ specification in version 5.2. * Tasking Routines:: @c * Resource Relinquishing Routines:: * Device Information Routines:: -@c * Device Memory Routines:: +* Device Memory Routines:: * Lock Routines:: * Timing Routines:: * Event Routine:: @@ -1658,25 +1658,298 @@ For OpenMP 5.1, this must be equal to the value returned by the -@c @node Device Memory Routines -@c @section Device Memory Routines -@c -@c Routines related to memory allocation and managing corresponding -@c pointers on devices. They have C linkage and do not throw exceptions. -@c -@c @menu -@c * omp_target_alloc:: -@c * omp_target_free:: -@c * omp_target_is_present:: +@node Device Memory Routines +@section Device Memory Routines + +Routines related to memory allocation and managing corresponding +pointers on devices. They have C linkage and do not throw exceptions. + +@menu +* omp_target_alloc:: Allocate device memory +* omp_target_free:: Free device memory +* omp_target_is_present:: Check whether storage is mapped @c * omp_target_is_accessible:: @c * omp_target_memcpy:: @c * omp_target_memcpy_rect:: @c * omp_target_memcpy_async:: @c * omp_target_memcpy_rect_async:: -@c * omp_target_associate_ptr:: -@c * omp_target_disassociate_ptr:: -@c * omp_get_mapped_ptr:: -@c @end menu +@c * omp_target_memset:: /TR12 +@c * omp_target_memset_async:: /TR12 +* omp_target_associate_ptr:: Associate a device pointer with a host pointer +* omp_target_disassociate_ptr:: Remove device--host pointer association +* omp_get_mapped_ptr:: Return device pointer to a host pointer +@end menu + + + +@node omp_target_alloc +@subsection @code{omp_target_alloc} -- Allocate device memory +@table @asis +@item @emph{Description}: +This routine allocates @var{size} bytes of memory in the device environment +associated with the device number @var{device_num}. If successful, a device +pointer is returned, otherwise a null pointer. + +In GCC, when the device is the host or the device shares memory with the host, +the memory is allocated on the host; in that case, when @var{size} is zero, +either NULL or a unique pointer value that can later be successfully passed to +@code{omp_target_free} is returned. When the allocation is not performed on +the host, a null pointer is returned when @var{size} is zero; in that case, +additionally a diagnostic might be printed to standard error (stderr). + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void *omp_target_alloc(size_t size, int device_num)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_target_alloc(size, device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_int, c_size_t} +@item @tab @code{integer(c_size_t), value :: size} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_free}, @ref{omp_target_associate_ptr} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.1 +@end table + + + +@node omp_target_free +@subsection @code{omp_target_free} -- Free device memory +@table @asis +@item @emph{Description}: +This routine frees memory allocated by the @code{omp_target_alloc} routine. +The @var{device_ptr} argument must be either a null pointer or a device pointer +returned by @code{omp_target_alloc} for the specified @code{device_num}. The +device number @var{device_num} must be a conforming device number. + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void omp_target_free(void *device_ptr, int device_num)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{subroutine omp_target_free(device_ptr, device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_int} +@item @tab @code{type(c_ptr), value :: device_ptr} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_alloc}, @ref{omp_target_disassociate_ptr} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.2 +@end table + + + +@node omp_target_is_present +@subsection @code{omp_target_is_present} -- Check whether storage is mapped +@table @asis +@item @emph{Description}: +This routine tests whether storage, identified by the host pointer @var{ptr} +is mapped to the device specified by @var{device_num}. If so, it returns +@emph{true} and otherwise @emph{false}. + +In GCC, this includes self mapping such that @code{omp_target_is_present} +returns @emph{true} when @var{device_num} specifies the host or when the host +and the device share memory. If @var{ptr} is a null pointer, @var{true} is +returned and if @var{device_num} is an invalid device number, @var{false} is +returned. + +If those conditions do not apply, @emph{true} is returned if the association has +been established by an explicit or implicit @code{map} clause, the +@code{declare target} directive or a call to the @code{omp_target_associate_ptr} +routine. + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{int omp_target_is_present(const void *ptr,} +@item @tab @code{ int device_num)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer(c_int) function omp_target_is_present(ptr, &} +@item @tab @code{ device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_int} +@item @tab @code{type(c_ptr), value :: ptr} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_associate_ptr} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.3 +@end table + + + +@node omp_target_associate_ptr +@subsection @code{omp_target_associate_ptr} -- Associate a device pointer with a host pointer +@table @asis +@item @emph{Description}: +This routine associates storage on the host with storage on a device identified +by @var{device_num}. The device pointer is usually obtained by calling +@code{omp_target_alloc} or by other means (but not by using the @code{map} +clauses or the @code{declare target} directive). The host pointer should point +to memory that has a storage size of at least @var{size}. + +The @var{device_offset} parameter specifies the offset into @var{device_ptr} +that is used as the base address for the device side of the mapping; the +storage size should be at least @var{device_offset} plus @var{size}. + +After the association, the host pointer can be used in a @code{map} clause and +in the @code{to} and @code{from} clauses of the @code{target update} directive +to transfer data between the associated pointers. The reference count of such +associated storage is infinite. The association can be removed by calling +@code{omp_target_disassociate_ptr} which should be done before the lifetime +of either either storage ends. + +The routine returns nonzero (@code{EINVAL}) when the @var{device_num} invalid, +for when the initial device or the associated device shares memory with the +host. @code{omp_target_associate_ptr} returns zero if @var{host_ptr} points +into already associated storage that is fully inside of a previously associated +memory. Otherwise, if the association was successful zero is returned; if none +of the cases above apply, nonzero (@code{EINVAL}) is returned. + +The @code{omp_target_is_present} routine can be used to test whether +associated storage for a device pointer exists. + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{int omp_target_associate_ptr(const void *host_ptr,} +@item @tab @code{ const void *device_ptr,} +@item @tab @code{ size_t size,} +@item @tab @code{ size_t device_offset,} +@item @tab @code{ int device_num)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer(c_int) function omp_target_associate_ptr(host_ptr, &} +@item @tab @code{ device_ptr, size, device_offset, device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_int, c_size_t} +@item @tab @code{type(c_ptr), value :: host_ptr, device_ptr} +@item @tab @code{integer(c_size_t), value :: size, device_offset} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_disassociate_ptr}, @ref{omp_target_is_present}, +@ref{omp_target_alloc} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.9 +@end table + + + +@node omp_target_disassociate_ptr +@subsection @code{omp_target_disassociate_ptr} -- Remove device--host pointer association +@table @asis +@item @emph{Description}: +This routine removes the storage association established by calling +@code{omp_target_associate_ptr} and sets the reference count to zero, +even if @code{omp_target_associate_ptr} was invoked multiple times for +for host pointer @code{ptr}. If applicable, the device memory needs +to be freed by the user. + +If an associated device storage location for the @var{device_num} was +found and has infinite reference count, the association is removed and +zero is returned. In all other cases, nonzero (@code{EINVAL}) is returned +and no other action is taken. + +Note that passing a host pointer where the association to the device pointer +was established with the @code{declare target} directive yields undefined +behavior. + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{int omp_target_disassociate_ptr(const void *ptr,} +@item @tab @code{ int device_num)} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{integer(c_int) function omp_target_disassociate_ptr(ptr, &} +@item @tab @code{ device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_int} +@item @tab @code{type(c_ptr), value :: ptr} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_associate_ptr} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.10 +@end table + + + +@node omp_get_mapped_ptr +@subsection @code{omp_get_mapped_ptr} -- Return device pointer to a host pointer +@table @asis +@item @emph{Description}: +If the device number is refers to the initial device or to a device with +memory accessible from the host (shared memory), the @code{omp_get_mapped_ptr} +routines returnes the value of the passed @var{ptr}. Otherwise, if associated +storage to the passed host pointer @var{ptr} exists on device associated with +@var{device_num}, it returns that pointer. In all other cases and in cases of +an error, a null pointer is returned. + +The association of storage location is established either via an explicit or +implicit @code{map} clause, the @code{declare target} directive or the +@code{omp_target_associate_ptr} routine. + +Running this routine in a @code{target} region except on the initial device +is not supported. + +@item @emph{C/C++} +@multitable @columnfractions .20 .80 +@item @emph{Prototype}: @tab @code{void *omp_get_mapped_ptr(const void *ptr, int device_num);} +@end multitable + +@item @emph{Fortran}: +@multitable @columnfractions .20 .80 +@item @emph{Interface}: @tab @code{type(c_ptr) function omp_get_mapped_ptr(ptr, device_num) bind(C)} +@item @tab @code{use, intrinsic :: iso_c_binding, only: c_ptr, c_int} +@item @tab @code{type(c_ptr), value :: ptr} +@item @tab @code{integer(c_int), value :: device_num} +@end multitable + +@item @emph{See also}: +@ref{omp_target_associate_ptr} + +@item @emph{Reference}: +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 18.8.11 +@end table + + @node Lock Routines @section Lock Routines