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.
int omp_target_associate_ptr(
const void *host_ptr,
const void *device_ptr,
size_t size,
size_t device_offset,
int device_num
);
Constraints on ArgumentsThe 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 the result of omp_get_num_devices() or equal to the result of a call to omp_get_initial_device().
EffectThe 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 disassociating it. When called from within a target region the effect of this routine is unspecified. 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.
Execution Model EventsThe target-data-associate event occurs when a thread associates data on a target device.
Tool CallbacksA thread invokes a registered ompt_callback_target_data_op callback for each occurrence of a target-data-associate event in that thread. The callback occurs in the context of the target task and has type signature ompt_callback_target_data_op_t.