openmp/libomptarget/docs/declare_target_indirect.md

   1 # Overview
   2
   3 The indirect clause enables **indirect device invocation** for a procedure:
   4 > 19 An indirect call to the device version of a procedure on a device other than the host<br>
   5 > 20 device, through a function pointer (C/C++), a pointer to a member function (C++) or<br>
   6 > 21 a procedure pointer (Fortran) that refers to the host version of the procedure.
   7
   8 # Compiler support
   9 ### Offload entry metadata (C++ FE)
  10
  11 For each function declared as **declare target indirect** C++ FE generates the following offload metadata:
  12
  13 ```c++
  14 // Entry 0 -> Kind of this type of metadata (2)
  15 // Entry 1 -> Mangled name of the function.
  16 // Entry 2 -> Order the entry was created.
  17 ```
  18
  19 The offloading metadata uses new `OffloadEntriesInfoManagerTy::OffloadingEntryInfoKinds::OffloadingEntryInfoDeviceIndirectFunc`  metadata kind.
  20
  21 ### Offload entries table
  22
  23 The offload entries table that is created for the host and for each of the device images currently have entries for **declare target** global variables, **omp target** outlined functions and constructor/destructor thunks for **declare target** global variables.
  24
  25
  26 Compiler will also produce an entry for each procedure listed in **indirect** clause of **declare target** construct:
  27 ```C++
  28 struct __tgt_offload_entry {
  29   void *addr;       // Pointer to the function
  30   char *name;       // Name of the function
  31   size_t size;      // 0 for function
  32   int32_t flags;    // OpenMPOffloadingDeclareTargetFlags::OMP_DECLARE_TARGET_FPTR
  33   int32_t reserved; // Reserved
  34 };
  35 ```
  36
  37 ### Run-time dispatch in device code
  38
  39 When an indirect function call is generated by a FE in **device code** it translates the original function pointer (which may be an address of a host function) into the device function pointer using a translation API, and uses the resulting function pointer for the call.
  40
  41 Original call code:
  42
  43 ```
  44   %0 = load void ()*, void ()** %fptr.addr
  45   call void %0()
  46 ```
  47
  48 Becomes this:
  49
  50 ```
  51   %0 = load void ()*, void ()** %fptr.addr
  52   %1 = bitcast void ()* %0 to i8*
  53   %call = call i8* @__kmpc_target_translate_fptr(i8* %1)
  54   %fptr_device = bitcast i8* %call to void ()*
  55   call void %fptr_device()
  56 ```
  57
  58 Device RTLs must provide the translation API:
  59
  60 ```c++
  61 // Translate \p FnPtr identifying a host function into a function pointer
  62 // identifying its device counterpart.
  63 // If \p FnPtr matches an address of any host function
  64 // declared as 'declare target indirect', then the API
  65 // must return an address of the same function compiled
  66 // for the device. If \p FnPtr does not match an address
  67 // of any host function, then the API returns \p FnPtr
  68 // unchanged.
  69 EXTERN void *__kmpc_target_translate_fptr(void *FnPtr);
  70 ```
  71
  72 # Runtime handling of function pointers
  73
  74 `OpenMPOffloadingDeclareTargetFlags::OMP_DECLARE_TARGET_FPTR` is a new flag to distinguish offload entries for function pointers from other function entries.  Unlike other function entries (with `size` equal to 0) `omptarget::InitLibrary()` will establish mapping for function pointer entries in `Device.HostDataToTargetMap`.
  75
  76 For each `OMP_DECLARE_TARGET_FPTR` entry in the offload entries table `libomptarget` creates an entry of the following type:
  77
  78 ```c++
  79 struct __omp_offloading_fptr_map_ty {
  80   int64_t host_ptr; // key
  81   int64_t tgt_ptr;  // value
  82 };
  83 ```
  84
  85 Where `host_ptr` is `__tgt_offload_entry::addr` in a **host** offload entry, and `tgt_ptr` is `__tgt_offload_entry::addr` in the corresponding **device** offload entry (which may be found using the populated `Device.HostDataToTargetMap`).
  86
  87 When all `__omp_offloading_function_ptr_map_ty` entries are collected in a single host array, `libomptarget` sorts the table by `host_ptr` values and passes it to the device plugin for registration, if plugin supports optional `__tgt_rtl_set_function_ptr_map` API.
  88
  89 Plugins may provide the following API, if they want to support **declare target indirect** functionality:
  90
  91 ```c++
  92 // Register in a target implementation defined way a table
  93 // of __omp_offloading_function_ptr_map_ty entries providing
  94 // mapping between host and device addresses of 'declare target indirect'
  95 // functions. \p table_size is the number of elements in \p table_host_ptr
  96 // array.
  97 EXTERN void __tgt_rtl_set_function_ptr_map(
  98     int32_t device_id, uint64_t table_size, __omp_offloading_fptr_map_ty *table_host_ptr);
  99 ```
 100
 101 # Sample implementation
 102
 103 This section describes one of potential implementations.
 104
 105 A FE may define the following global symbols for each translation module containing **declare target indirect**, when compiling this module for a device:
 106
 107 ```c++
 108 // Mapping between host and device functions declared as
 109 // 'declare target indirect'.
 110 __attribute__((weak)) struct __omp_offloading_fptr_map_ty {
 111   int64_t host_ptr; // key
 112   int64_t tgt_ptr;  // value
 113 } *__omp_offloading_fptr_map_p = 0;
 114
 115 // Number of elements in __omp_offloading_fptr_map_p table.
 116 __attribute__((weak)) uint64_t __omp_offloading_fptr_map_size = 0;
 117 ```
 118
 119 `__tgt_rtl_set_function_ptr_map(int32_t device_id, uint64_t table_size, __omp_offloading_fptr_map_ty *table_host_ptr)` allocates device memory of size `sizeof(__omp_offloading_fptr_map_ty) * table_size`, and transfers the contents of `table_host_ptr` array into this device memory.  An address of the allocated device memory area is then assigned to `__omp_offloading_fptr_map_p` global variables on the device.  For example, in **CUDA**, a device address of `__omp_offloading_fptr_map_p` may be taken by calling `cuModuleGetGlobal`, and then a pointer-sized data transfer will initialize `__omp_offloading_fptr_map_p` to point to the device copy of `table_host_ptr` array.  `__omp_offloading_fptr_map_size` is assigned to `table_size` the same way.
 120
 121 An alternative implementation of `__tgt_rtl_set_function_ptr_map` may invoke a device kernel that will do the assignments.
 122
 123 `__kmpc_target_translate_fptr(void *FnPtr)` API uses binary search to match `FnPtr` against `host_ptr` inside the device table pointed to by `__omp_offloading_fptr_map_p`.  If the matching key is found, it returns the corresponding `tgt_ptr`, otherwise, it returns `FnPtr`.
 124
 125 # TODO: Optimization for non-unified_shared_memory
 126
 127 If a program does not use **required unified_shared_memory**, and all function pointers are mapped (not a requirement by OpenMP spec), then an implementation may avoid the runtime dispatch code for indirect function calls (i.e. `__kmpc_target_translate_fptr` is not needed) and also `__tgt_rtl_set_function_ptr_map` is not needed.  `libomptarget` will just map the function pointers as regular data pointers via `Device.HostDataToTargetMap`.