Summary
The omp_target_memcpy_rect routine copies a rectangular subvolume from a multi-dimensional
array to another multi-dimensional array. The omp_target_memcpy_rect routine performs a copy
between any combination of host and device pointers.
Constraints on Arguments
Each device pointer specified must be valid for the device on the same side of the copy. The dst_device_num
and src_device_num arguments must be greater than or equal to zero and less than or equal to the result of
omp_get_num_devices().
The length of the offset and dimension arrays must be at least the value of num_dims. The value of
num_dims must be between 1 and the implementation-defined limit, which must be at least
three.
Because the interface binds directly to a C language function the function assumes C memory
ordering.
Binding
The binding task set for an omp_target_memcpy_rect region is the generating task, which is the
target task generated by the call to the omp_target_memcpy_rect routine.
Effect
This routine copies a rectangular subvolume of src, in the device data environment of device
src_device_num, to dst, in the device data environment of device dst_device_num. The volume is specified
in terms of the size of an element, number of dimensions, and constant arrays of length num_dims. The
maximum number of dimensions supported is at least three; support for higher dimensionality is
implementation defined. The volume array specifies the length, in number of elements, to copy in each
dimension from src to dst. The dst_offsets (src_offsets) parameter specifies the number of elements from the
origin of dst (src) in elements. The dst_dimensions (src_dimensions) parameter specifies the length of each
dimension of dst (src).
The omp_target_memcpy_rect 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. The routine contains a task
scheduling point.
An application can determine the inclusive number of dimensions supported by an implementation by
passing NULL pointers for both dst and src. The routine returns the number of dimensions supported by the
implementation for the specified device numbers. No copy operation is performed.
The omp_target_memcpy_rect routine requires an explicit interface and so might not be provided in
omp_lib.h.
Execution Model Events
The target-data-op-begin event occurs before a thread initiates a data transfer.
The target-data-op-end event occurs after a thread initiated a data transfer.
Tool Callbacks
A thread dispatches a registered ompt_callback_target_data_op_emi callback with
ompt_scope_begin as its endpoint argument for each occurrence of a target-data-op-begin event in that
thread. Similarly, a thread dispatches a registered ompt_callback_target_data_op_emi callback
with ompt_scope_end as its endpoint argument for each occurrence of a target-data-op-end event in that
thread. These callbacks have type signature ompt_callback_target_data_op_emi_t.
A thread dispatches a registered ompt_callback_target_data_op callback for each occurrence of a
target-data-op-end event in that thread. The callback occurs in the context of the target task and has type
signature ompt_callback_target_data_op_t.
Restrictions
Restrictions to the omp_target_memcpy_rect routine are as follows.
When
called
from
within
a
target
region
the
effect
is
unspecified.