openmp/libomptarget/include/omptargetplugin.h

   1 //===-- omptargetplugin.h - Target dependent OpenMP Plugin API --*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // This file defines an interface between target independent OpenMP offload
  10 // runtime library libomptarget and target dependent plugin.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef _OMPTARGETPLUGIN_H_
  15 #define _OMPTARGETPLUGIN_H_
  16
  17 #include <omptarget.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 // First method called on the plugin
  24 int32_t __tgt_rtl_init_plugin();
  25
  26 // Last method called on the plugin
  27 int32_t __tgt_rtl_deinit_plugin();
  28
  29 // Return the number of available devices of the type supported by the
  30 // target RTL.
  31 int32_t __tgt_rtl_number_of_devices(void);
  32
  33 // Return an integer different from zero if the provided device image can be
  34 // supported by the runtime. The functionality is similar to comparing the
  35 // result of __tgt__rtl__load__binary to NULL. However, this is meant to be a
  36 // lightweight query to determine if the RTL is suitable for an image without
  37 // having to load the library, which can be expensive.
  38 int32_t __tgt_rtl_is_valid_binary(__tgt_device_image *Image);
  39
  40 // This provides the same functionality as __tgt_rtl_is_valid_binary except we
  41 // also use additional information to determine if the image is valid. This
  42 // allows us to determine if an image has a compatible architecture.
  43 int32_t __tgt_rtl_is_valid_binary_info(__tgt_device_image *Image,
  44                                        __tgt_image_info *Info);
  45
  46 // Return an integer other than zero if the data can be exchaned from SrcDevId
  47 // to DstDevId. If it is data exchangable, the device plugin should provide
  48 // function to move data from source device to destination device directly.
  49 int32_t __tgt_rtl_is_data_exchangable(int32_t SrcDevId, int32_t DstDevId);
  50
  51 // Return an integer other than zero if the plugin can handle images which do
  52 // not contain target regions and global variables (but can contain other
  53 // functions)
  54 int32_t __tgt_rtl_supports_empty_images();
  55
  56 // Initialize the requires flags for the device.
  57 int64_t __tgt_rtl_init_requires(int64_t RequiresFlags);
  58
  59 // Initialize the specified device. In case of success return 0; otherwise
  60 // return an error code.
  61 int32_t __tgt_rtl_init_device(int32_t ID);
  62
  63 // Deinitialize the specified device. In case of success return 0; otherwise
  64 // return an error code.
  65 int32_t __tgt_rtl_deinit_device(int32_t ID);
  66
  67 // Pass an executable image section described by image to the specified
  68 // device and prepare an address table of target entities. In case of error,
  69 // return NULL. Otherwise, return a pointer to the built address table.
  70 // Individual entries in the table may also be NULL, when the corresponding
  71 // offload region is not supported on the target device.
  72 __tgt_target_table *__tgt_rtl_load_binary(int32_t ID,
  73                                           __tgt_device_image *Image);
  74
  75 // Allocate data on the particular target device, of the specified size.
  76 // HostPtr is a address of the host data the allocated target data
  77 // will be associated with (HostPtr may be NULL if it is not known at
  78 // allocation time, like for example it would be for target data that
  79 // is allocated by omp_target_alloc() API). Return address of the
  80 // allocated data on the target that will be used by libomptarget.so to
  81 // initialize the target data mapping structures. These addresses are
  82 // used to generate a table of target variables to pass to
  83 // __tgt_rtl_run_region(). The __tgt_rtl_data_alloc() returns NULL in
  84 // case an error occurred on the target device. Kind dictates what allocator
  85 // to use (e.g. shared, host, device).
  86 void *__tgt_rtl_data_alloc(int32_t ID, int64_t Size, void *HostPtr,
  87                            int32_t Kind);
  88
  89 // Pass the data content to the target device using the target address. In case
  90 // of success, return zero. Otherwise, return an error code.
  91 int32_t __tgt_rtl_data_submit(int32_t ID, void *TargetPtr, void *HostPtr,
  92                               int64_t Size);
  93
  94 int32_t __tgt_rtl_data_submit_async(int32_t ID, void *TargetPtr, void *HostPtr,
  95                                     int64_t Size, __tgt_async_info *AsyncInfo);
  96
  97 // Retrieve the data content from the target device using its address. In case
  98 // of success, return zero. Otherwise, return an error code.
  99 int32_t __tgt_rtl_data_retrieve(int32_t ID, void *HostPtr, void *TargetPtr,
 100                                 int64_t Size);
 101
 102 // Asynchronous version of __tgt_rtl_data_retrieve
 103 int32_t __tgt_rtl_data_retrieve_async(int32_t ID, void *HostPtr,
 104                                       void *TargetPtr, int64_t Size,
 105                                       __tgt_async_info *AsyncInfo);
 106
 107 // Copy the data content from one target device to another target device using
 108 // its address. This operation does not need to copy data back to host and then
 109 // from host to another device. In case of success, return zero. Otherwise,
 110 // return an error code.
 111 int32_t __tgt_rtl_data_exchange(int32_t SrcID, void *SrcPtr, int32_t DstID,
 112                                 void *DstPtr, int64_t Size);
 113
 114 // Asynchronous version of __tgt_rtl_data_exchange
 115 int32_t __tgt_rtl_data_exchange_async(int32_t SrcID, void *SrcPtr,
 116                                       int32_t DesID, void *DstPtr, int64_t Size,
 117                                       __tgt_async_info *AsyncInfo);
 118
 119 // De-allocate the data referenced by target ptr on the device. In case of
 120 // success, return zero. Otherwise, return an error code. Kind dictates what
 121 // allocator to use (e.g. shared, host, device).
 122 int32_t __tgt_rtl_data_delete(int32_t ID, void *TargetPtr, int32_t Kind);
 123
 124 // Transfer control to the offloaded entry Entry on the target device.
 125 // Args and Offsets are arrays of NumArgs size of target addresses and
 126 // offsets. An offset should be added to the target address before passing it
 127 // to the outlined function on device side. If AsyncInfo is nullptr, it is
 128 // synchronous; otherwise it is asynchronous. However, AsyncInfo may be
 129 // ignored on some platforms, like x86_64. In that case, it is synchronous. In
 130 // case of success, return zero. Otherwise, return an error code.
 131 int32_t __tgt_rtl_run_target_region(int32_t ID, void *Entry, void **Args,
 132                                     ptrdiff_t *Offsets, int32_t NumArgs);
 133
 134 // Asynchronous version of __tgt_rtl_run_target_region
 135 int32_t __tgt_rtl_run_target_region_async(int32_t ID, void *Entry, void **Args,
 136                                           ptrdiff_t *Offsets, int32_t NumArgs,
 137                                           __tgt_async_info *AsyncInfo);
 138
 139 // Similar to __tgt_rtl_run_target_region, but additionally specify the
 140 // number of teams to be created and a number of threads in each team. If
 141 // AsyncInfo is nullptr, it is synchronous; otherwise it is asynchronous.
 142 // However, AsyncInfo may be ignored on some platforms, like x86_64. In that
 143 // case, it is synchronous.
 144 int32_t __tgt_rtl_run_target_team_region(int32_t ID, void *Entry, void **Args,
 145                                          ptrdiff_t *Offsets, int32_t NumArgs,
 146                                          int32_t NumTeams, int32_t ThreadLimit,
 147                                          uint64_t LoopTripcount);
 148
 149 // Asynchronous version of __tgt_rtl_run_target_team_region
 150 int32_t __tgt_rtl_run_target_team_region_async(
 151     int32_t ID, void *Entry, void **Args, ptrdiff_t *Offsets, int32_t NumArgs,
 152     int32_t NumTeams, int32_t ThreadLimit, uint64_t LoopTripcount,
 153     __tgt_async_info *AsyncInfo);
 154
 155 // Device synchronization. In case of success, return zero. Otherwise, return an
 156 // error code.
 157 int32_t __tgt_rtl_synchronize(int32_t ID, __tgt_async_info *AsyncInfo);
 158
 159 // Queries for the completion of asynchronous operations. Instead of blocking
 160 // the calling thread as __tgt_rtl_synchronize, the progress of the operations
 161 // stored in AsyncInfo->Queue is queried in a non-blocking manner, partially
 162 // advancing their execution. If all operations are completed, AsyncInfo->Queue
 163 // is set to nullptr. If there are still pending operations, AsyncInfo->Queue is
 164 // kept as a valid queue. In any case of success (i.e., successful query
 165 // with/without completing all operations), return zero. Otherwise, return an
 166 // error code.
 167 int32_t __tgt_rtl_query_async(int32_t ID, __tgt_async_info *AsyncInfo);
 168
 169 // Set plugin's internal information flag externally.
 170 void __tgt_rtl_set_info_flag(uint32_t);
 171
 172 // Print the device information
 173 void __tgt_rtl_print_device_info(int32_t ID);
 174
 175 // Event related interfaces. It is expected to use the interfaces in the
 176 // following way:
 177 // 1) Create an event on the target device (__tgt_rtl_create_event).
 178 // 2) Record the event based on the status of \p AsyncInfo->Queue at the moment
 179 // of function call to __tgt_rtl_record_event. An event becomes "meaningful"
 180 // once it is recorded, such that others can depend on it.
 181 // 3) Call __tgt_rtl_wait_event to set dependence on the event. Whether the
 182 // operation is blocking or non-blocking depends on the target. It is expected
 183 // to be non-blocking, just set dependence and return.
 184 // 4) Call __tgt_rtl_sync_event to sync the event. It is expected to block the
 185 // thread calling the function.
 186 // 5) Destroy the event (__tgt_rtl_destroy_event).
 187 // {
 188 int32_t __tgt_rtl_create_event(int32_t ID, void **Event);
 189
 190 int32_t __tgt_rtl_record_event(int32_t ID, void *Event,
 191                                __tgt_async_info *AsyncInfo);
 192
 193 int32_t __tgt_rtl_wait_event(int32_t ID, void *Event,
 194                              __tgt_async_info *AsyncInfo);
 195
 196 int32_t __tgt_rtl_sync_event(int32_t ID, void *Event);
 197
 198 int32_t __tgt_rtl_destroy_event(int32_t ID, void *Event);
 199 // }
 200
 201 int32_t __tgt_rtl_init_async_info(int32_t ID, __tgt_async_info **AsyncInfoPtr);
 202 int32_t __tgt_rtl_init_device_info(int32_t ID, __tgt_device_info *DeviceInfoPtr,
 203                                    const char **ErrStr);
 204
 205 // lock/pin host memory
 206 int32_t __tgt_rtl_data_lock(int32_t ID, void *HstPtr, int64_t Size,
 207                             void **LockedPtr);
 208
 209 // unlock/unpin host memory
 210 int32_t __tgt_rtl_data_unlock(int32_t ID, void *HstPtr);
 211
 212 // Notify the plugin about a new mapping starting at the host address \p HstPtr
 213 // and \p Size bytes. The plugin may lock/pin that buffer to achieve optimal
 214 // memory transfers involving that buffer.
 215 int32_t __tgt_rtl_data_notify_mapped(int32_t ID, void *HstPtr, int64_t Size);
 216
 217 // Notify the plugin about an existing mapping being unmapped, starting at the
 218 // host address \p HstPtr and \p Size bytes.
 219 int32_t __tgt_rtl_data_notify_unmapped(int32_t ID, void *HstPtr);
 220
 221 // Set the global device identifier offset, such that the plugin may determine a
 222 // unique device number.
 223 int32_t __tgt_rtl_set_device_offset(int32_t DeviceIdOffset);
 224
 225 #ifdef __cplusplus
 226 }
 227 #endif
 228
 229 #endif // _OMPTARGETPLUGIN_H_