OpenMP-Examples/devices/target_associate_ptr.tex
2024-04-16 08:59:23 -07:00

50 lines
2.5 KiB
TeX

%\newpage
\subsection{Device and Host Memory Association}
\label{subsec:target_associate_ptr}
\label{sec:target_associate_ptr}
\index{routines!omp_target_associate_ptr@\kcode{omp_target_associate_ptr}}
\index{omp_target_associate_ptr routine@\kcode{omp_target_associate_ptr} routine}
\index{routines!omp_target_alloc@\kcode{omp_target_alloc}}
\index{omp_target_alloc routine@\kcode{omp_target_alloc} routine}
The association of device memory with host memory
can be established by calling the \kcode{omp_target_associate_ptr}
API routine as part of the mapping.
The following example shows the use of this routine
to associate device memory of size \ucode{CS},
allocated by the \kcode{omp_target_alloc} routine and
pointed to by the device pointer \ucode{dev_ptr},
with a chunk of the host array \ucode{arr} starting at index \ucode{ioff}.
In Fortran, the intrinsic function \vcode{c_loc} is called
to obtain the corresponding C pointer (\ucode{h_ptr}) of \ucode{arr(ioff)}
for use in the call to the API routine.
\index{constructs!target update@\kcode{target update}}
\index{target update construct@\kcode{target update} construct}
\index{map clause@\kcode{map} clause!always modifier@\kcode{always} modifier}
\index{always modifier@\kcode{always} modifier}
Since the reference count of the resulting mapping is infinite,
it is necessary to use the \kcode{target update} directive (or
the \kcode{always} modifier in a \kcode{map} clause) to accomplish a
data transfer between host and device.
The explicit mapping of the array section \ucode{arr[ioff:CS]}
(or \ucode{arr(ioff:ioff+CS-1)} in Fortran) on the \kcode{target}
construct ensures that the allocated and associated device memory is used
when referencing the array \ucode{arr} in the \kcode{target} region.
The device pointer \ucode{dev_ptr} cannot be accessed directly
after a call to the \kcode{omp_target_associate_ptr} routine.
\index{routines!omp_target_disassociate_ptr@\kcode{omp_target_disassociate_ptr}}
\index{omp_target_disassociate_ptr routine@\kcode{omp_target_disassociate_ptr} routine}
\index{routines!omp_target_free@\kcode{omp_target_free}}
\index{omp_target_free routine@\kcode{omp_target_free} routine}
After the \kcode{target} region, the device pointer is disassociated from
the current chunk of the host memory by calling the \kcode{omp_target_disassociate_ptr} routine before working on the next chunk.
The device memory is freed by calling the \kcode{omp_target_free}
routine at the end.
\cexample[4.5]{target_associate_ptr}{1}
\ffreeexample[5.1]{target_associate_ptr}{1}