HOME
| OPENMP API Specification: Version 5.1 November 2020

3.8.9  omp_target_associate_ptr

Summary The omp_target_associate_ptr routine maps a device pointer, which may be returned from omp_target_alloc or implementation-defined runtime routines, to a host pointer.

Format

SVG-Viewer needed.

 

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

SVG-Viewer needed.

SVG-Viewer needed.

 

 
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_size_t, c_int 
type(c_ptr), value :: host_ptr, device_ptr 
integer(c_size_t), value :: size, device_offset 
integer(c_int), value :: device_num  

SVG-Viewer needed.

Constraints on Arguments The value of device_ptr value must be a valid pointer to device memory for the device denoted by the value of device_num. The device_num argument must be greater than or equal to zero and less than or equal to the result of omp_get_num_devices().

Binding The binding task set for an omp_target_associate_ptr region is the generating task, which is the target task generated by the call to the omp_target_associate_ptr routine.

Effect The omp_target_associate_ptr routine associates a device pointer in the device data environment of device device_num with a host pointer such that when the host pointer appears in a subsequent map clause, the associated device pointer is used as the target for data motion associated with that host pointer. 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 reference count of the resulting mapping will be infinite. After being successfully associated, the buffer to which the device pointer points is invalidated and accessing data directly through the device pointer results in unspecified behavior. The pointer can be retrieved for other uses by using the omp_target_disassociate_ptr routine to disassociate it .

The omp_target_associate_ptr routine executes as if part of a target task that is generated by the call to the routine and that is an included task.

The routine returns zero if successful. Otherwise it returns a non-zero value.

Only one device buffer can be associated with a given host pointer value and device number pair. Attempting to associate a second buffer will return non-zero. Associating the same pair of pointers on the same device with the same offset has no effect and returns zero. Associating pointers that share underlying storage will result in unspecified behavior. The omp_target_is_present function can be used to test whether a given host pointer has a corresponding variable in the device data environment.

SVG-Viewer needed.

The omp_target_associate_ptr routine requires an explicit interface and so might not be provided in omp_lib.h.

SVG-Viewer needed.

Execution Model Events The target-data-associate event occurs before a thread initiates a device pointer association on a target device.

Tool Callbacks A thread dispatches a registered ompt_callback_target_data_op callback, or a registered ompt_callback_target_data_op_emi callback with ompt_scope_beginend as its endpoint argument for each occurrence of a target-data-associate event in that thread. These callbacks have type signature ompt_callback_target_data_op_t or ompt_callback_target_data_op_emi_t, respectively.

Restrictions Restrictions to the omp_target_associate_ptr routine are as follows.

Cross References