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. 121 int32_t __tgt_rtl_data_delete(int32_t ID, void *TargetPtr); 122 123 // Transfer control to the offloaded entry Entry on the target device. 124 // Args and Offsets are arrays of NumArgs size of target addresses and 125 // offsets. An offset should be added to the target address before passing it 126 // to the outlined function on device side. If AsyncInfo is nullptr, it is 127 // synchronous; otherwise it is asynchronous. However, AsyncInfo may be 128 // ignored on some platforms, like x86_64. In that case, it is synchronous. In 129 // case of success, return zero. Otherwise, return an error code. 130 int32_t __tgt_rtl_run_target_region(int32_t ID, void *Entry, void **Args, 131 ptrdiff_t *Offsets, int32_t NumArgs); 132 133 // Asynchronous version of __tgt_rtl_run_target_region 134 int32_t __tgt_rtl_run_target_region_async(int32_t ID, void *Entry, void **Args, 135 ptrdiff_t *Offsets, int32_t NumArgs, 136 __tgt_async_info *AsyncInfo); 137 138 // Similar to __tgt_rtl_run_target_region, but additionally specify the 139 // number of teams to be created and a number of threads in each team. If 140 // AsyncInfo is nullptr, it is synchronous; otherwise it is asynchronous. 141 // However, AsyncInfo may be ignored on some platforms, like x86_64. In that 142 // case, it is synchronous. 143 int32_t __tgt_rtl_run_target_team_region(int32_t ID, void *Entry, void **Args, 144 ptrdiff_t *Offsets, int32_t NumArgs, 145 int32_t NumTeams, int32_t ThreadLimit, 146 uint64_t LoopTripcount); 147 148 // Asynchronous version of __tgt_rtl_run_target_team_region 149 int32_t __tgt_rtl_run_target_team_region_async( 150 int32_t ID, void *Entry, void **Args, ptrdiff_t *Offsets, int32_t NumArgs, 151 int32_t NumTeams, int32_t ThreadLimit, uint64_t LoopTripcount, 152 __tgt_async_info *AsyncInfo); 153 154 // Device synchronization. In case of success, return zero. Otherwise, return an 155 // error code. 156 int32_t __tgt_rtl_synchronize(int32_t ID, __tgt_async_info *AsyncInfo); 157 158 // Set plugin's internal information flag externally. 159 void __tgt_rtl_set_info_flag(uint32_t); 160 161 // Print the device information 162 void __tgt_rtl_print_device_info(int32_t ID); 163 164 // Event related interfaces. It is expected to use the interfaces in the 165 // following way: 166 // 1) Create an event on the target device (__tgt_rtl_create_event). 167 // 2) Record the event based on the status of \p AsyncInfo->Queue at the moment 168 // of function call to __tgt_rtl_record_event. An event becomes "meaningful" 169 // once it is recorded, such that others can depend on it. 170 // 3) Call __tgt_rtl_wait_event to set dependence on the event. Whether the 171 // operation is blocking or non-blocking depends on the target. It is expected 172 // to be non-blocking, just set dependence and return. 173 // 4) Call __tgt_rtl_sync_event to sync the event. It is expected to block the 174 // thread calling the function. 175 // 5) Destroy the event (__tgt_rtl_destroy_event). 176 // { 177 int32_t __tgt_rtl_create_event(int32_t ID, void **Event); 178 179 int32_t __tgt_rtl_record_event(int32_t ID, void *Event, 180 __tgt_async_info *AsyncInfo); 181 182 int32_t __tgt_rtl_wait_event(int32_t ID, void *Event, 183 __tgt_async_info *AsyncInfo); 184 185 int32_t __tgt_rtl_sync_event(int32_t ID, void *Event); 186 187 int32_t __tgt_rtl_destroy_event(int32_t ID, void *Event); 188 // } 189 190 int32_t __tgt_rtl_init_async_info(int32_t ID, __tgt_async_info **AsyncInfoPtr); 191 int32_t __tgt_rtl_init_device_info(int32_t ID, __tgt_device_info *DeviceInfoPtr, 192 const char **ErrStr); 193 194 #ifdef __cplusplus 195 } 196 #endif 197 198 #endif // _OMPTARGETPLUGIN_H_ 199