HOME
| OPENMP API Specification: Version 5.1 November 2020

3.8.6  omp_target_memcpy_rect

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.

Format

SVG-Viewer needed.

 

 
int omp_target_memcpy_rect( 
  void *dst, 
  const void *src, 
  size_t element_size, 
  int num_dims, 
  const size_t *volume, 
  const size_t *dst_offsets, 
  const size_t *src_offsets, 
  const size_t *dst_dimensions, 
  const size_t *src_dimensions, 
  int dst_device_num, 
  int src_device_num 
);  

SVG-Viewer needed.

SVG-Viewer needed.

 

 
integer(c_int) function omp_target_memcpy_rect(dst,src,element_size, & 
  num_dims, volume, dst_offsets, src_offsets, dst_dimensions, src_dimensions, & 
  dst_device_num, src_device_num) bind(c) 
use, intrinsic :: iso_c_binding, only : c_ptr, c_int, c_size_t 
type(c_ptr), value :: dst, src 
integer(c_size_t), value :: element_size 
integer(c_int), value :: num_dims, dst_device_num, src_device_num 
integer(c_size_t), intent(in) :: volume(*), dst_offsets(*), & 
  src_offsets(*), dst_dimensions(*), src_dimensions(*)  

SVG-Viewer needed.

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.

SVG-Viewer needed.

Because the interface binds directly to a C language function the function assumes C memory ordering.

SVG-Viewer needed.

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.

SVG-Viewer needed.

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

SVG-Viewer needed.

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.

Cross References