---

3.7.9 omp_target_associate_ptr – Associate a device pointer with a host pointer ¶

Description:

This routine associates storage on the host with storage on a device identified by device_num. The device pointer is usually obtained by calling omp_target_alloc or by other means (but not by using the map clauses or the declare target directive). The host pointer should point to memory that has a storage size of at least size.

The device_offset parameter specifies the offset into device_ptr that is used as the base address for the device side of the mapping; the storage size should be at least device_offset plus size.

After the association, the host pointer can be used in a map clause and in the to and from clauses of the 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 omp_target_disassociate_ptr which should be done before the lifetime of either storage ends.

The routine returns nonzero (EINVAL) when the device_num invalid, for when the initial device or the associated device shares memory with the host. omp_target_associate_ptr returns zero if 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 (EINVAL) is returned.

The omp_target_is_present routine can be used to test whether associated storage for a device pointer exists.

Running this routine in a target region except on the initial device is not supported.

C/C++

Prototype:	int omp_target_associate_ptr(const void *host_ptr,
	const void *device_ptr,
	size_t size,
	size_t device_offset,
	int device_num)

Fortran:

Interface:	integer(c_int) function omp_target_associate_ptr(host_ptr, &
	device_ptr, size, device_offset, device_num) bind(C)
	use, intrinsic :: iso_c_binding, only: c_ptr, c_int, c_size_t
	type(c_ptr), value :: host_ptr, device_ptr
	integer(c_size_t), value :: size, device_offset
	integer(c_int), value :: device_num

See also:

omp_target_disassociate_ptr – Remove device–host pointer association, omp_target_is_present – Check whether storage is mapped, omp_target_alloc – Allocate device memory

Reference:

OpenMP specification v5.1, Section 3.8.9