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 // Return the number of available devices of the type supported by the 24 // target RTL. 25 int32_t __tgt_rtl_number_of_devices(void); 26 27 // Return an integer different from zero if the provided device image can be 28 // supported by the runtime. The functionality is similar to comparing the 29 // result of __tgt__rtl__load__binary to NULL. However, this is meant to be a 30 // lightweight query to determine if the RTL is suitable for an image without 31 // having to load the library, which can be expensive. 32 int32_t __tgt_rtl_is_valid_binary(__tgt_device_image *Image); 33 34 // This provides the same functionality as __tgt_rtl_is_valid_binary except we 35 // also use additional information to determine if the image is valid. This 36 // allows us to determine if an image has a compatible architecture. 37 int32_t __tgt_rtl_is_valid_binary_info(__tgt_device_image *Image, 38 __tgt_image_info *Info); 39 40 // Return an integer other than zero if the data can be exchaned from SrcDevId 41 // to DstDevId. If it is data exchangable, the device plugin should provide 42 // function to move data from source device to destination device directly. 43 int32_t __tgt_rtl_is_data_exchangable(int32_t SrcDevId, int32_t DstDevId); 44 45 // Return an integer other than zero if the plugin can handle images which do 46 // not contain target regions and global variables (but can contain other 47 // functions) 48 int32_t __tgt_rtl_supports_empty_images(); 49 50 // Initialize the requires flags for the device. 51 int64_t __tgt_rtl_init_requires(int64_t RequiresFlags); 52 53 // Initialize the specified device. In case of success return 0; otherwise 54 // return an error code. 55 int32_t __tgt_rtl_init_device(int32_t ID); 56 57 // Deinitialize the specified device. In case of success return 0; otherwise 58 // return an error code. 59 int32_t __tgt_rtl_deinit_device(int32_t ID); 60 61 // Pass an executable image section described by image to the specified 62 // device and prepare an address table of target entities. In case of error, 63 // return NULL. Otherwise, return a pointer to the built address table. 64 // Individual entries in the table may also be NULL, when the corresponding 65 // offload region is not supported on the target device. 66 __tgt_target_table *__tgt_rtl_load_binary(int32_t ID, 67 __tgt_device_image *Image); 68 69 // Allocate data on the particular target device, of the specified size. 70 // HostPtr is a address of the host data the allocated target data 71 // will be associated with (HostPtr may be NULL if it is not known at 72 // allocation time, like for example it would be for target data that 73 // is allocated by omp_target_alloc() API). Return address of the 74 // allocated data on the target that will be used by libomptarget.so to 75 // initialize the target data mapping structures. These addresses are 76 // used to generate a table of target variables to pass to 77 // __tgt_rtl_run_region(). The __tgt_rtl_data_alloc() returns NULL in 78 // case an error occurred on the target device. Kind dictates what allocator 79 // to use (e.g. shared, host, device). 80 void *__tgt_rtl_data_alloc(int32_t ID, int64_t Size, void *HostPtr, 81 int32_t Kind); 82 83 // Pass the data content to the target device using the target address. In case 84 // of success, return zero. Otherwise, return an error code. 85 int32_t __tgt_rtl_data_submit(int32_t ID, void *TargetPtr, void *HostPtr, 86 int64_t Size); 87 88 int32_t __tgt_rtl_data_submit_async(int32_t ID, void *TargetPtr, void *HostPtr, 89 int64_t Size, __tgt_async_info *AsyncInfo); 90 91 // Retrieve the data content from the target device using its address. In case 92 // of success, return zero. Otherwise, return an error code. 93 int32_t __tgt_rtl_data_retrieve(int32_t ID, void *HostPtr, void *TargetPtr, 94 int64_t Size); 95 96 // Asynchronous version of __tgt_rtl_data_retrieve 97 int32_t __tgt_rtl_data_retrieve_async(int32_t ID, void *HostPtr, 98 void *TargetPtr, int64_t Size, 99 __tgt_async_info *AsyncInfo); 100 101 // Copy the data content from one target device to another target device using 102 // its address. This operation does not need to copy data back to host and then 103 // from host to another device. In case of success, return zero. Otherwise, 104 // return an error code. 105 int32_t __tgt_rtl_data_exchange(int32_t SrcID, void *SrcPtr, int32_t DstID, 106 void *DstPtr, int64_t Size); 107 108 // Asynchronous version of __tgt_rtl_data_exchange 109 int32_t __tgt_rtl_data_exchange_async(int32_t SrcID, void *SrcPtr, 110 int32_t DesID, void *DstPtr, int64_t Size, 111 __tgt_async_info *AsyncInfo); 112 113 // De-allocate the data referenced by target ptr on the device. In case of 114 // success, return zero. Otherwise, return an error code. 115 int32_t __tgt_rtl_data_delete(int32_t ID, void *TargetPtr); 116 117 // Transfer control to the offloaded entry Entry on the target device. 118 // Args and Offsets are arrays of NumArgs size of target addresses and 119 // offsets. An offset should be added to the target address before passing it 120 // to the outlined function on device side. If AsyncInfo is nullptr, it is 121 // synchronous; otherwise it is asynchronous. However, AsyncInfo may be 122 // ignored on some platforms, like x86_64. In that case, it is synchronous. In 123 // case of success, return zero. Otherwise, return an error code. 124 int32_t __tgt_rtl_run_target_region(int32_t ID, void *Entry, void **Args, 125 ptrdiff_t *Offsets, int32_t NumArgs); 126 127 // Asynchronous version of __tgt_rtl_run_target_region 128 int32_t __tgt_rtl_run_target_region_async(int32_t ID, void *Entry, void **Args, 129 ptrdiff_t *Offsets, int32_t NumArgs, 130 __tgt_async_info *AsyncInfo); 131 132 // Similar to __tgt_rtl_run_target_region, but additionally specify the 133 // number of teams to be created and a number of threads in each team. If 134 // AsyncInfo is nullptr, it is synchronous; otherwise it is asynchronous. 135 // However, AsyncInfo may be ignored on some platforms, like x86_64. In that 136 // case, it is synchronous. 137 int32_t __tgt_rtl_run_target_team_region(int32_t ID, void *Entry, void **Args, 138 ptrdiff_t *Offsets, int32_t NumArgs, 139 int32_t NumTeams, int32_t ThreadLimit, 140 uint64_t LoopTripcount); 141 142 // Asynchronous version of __tgt_rtl_run_target_team_region 143 int32_t __tgt_rtl_run_target_team_region_async( 144 int32_t ID, void *Entry, void **Args, ptrdiff_t *Offsets, int32_t NumArgs, 145 int32_t NumTeams, int32_t ThreadLimit, uint64_t LoopTripcount, 146 __tgt_async_info *AsyncInfo); 147 148 // Device synchronization. In case of success, return zero. Otherwise, return an 149 // error code. 150 int32_t __tgt_rtl_synchronize(int32_t ID, __tgt_async_info *AsyncInfo); 151 152 // Set plugin's internal information flag externally. 153 void __tgt_rtl_set_info_flag(uint32_t); 154 155 // Print the device information 156 void __tgt_rtl_print_device_info(int32_t ID); 157 158 // Event related interfaces. It is expected to use the interfaces in the 159 // following way: 160 // 1) Create an event on the target device (__tgt_rtl_create_event). 161 // 2) Record the event based on the status of \p AsyncInfo->Queue at the moment 162 // of function call to __tgt_rtl_record_event. An event becomes "meaningful" 163 // once it is recorded, such that others can depend on it. 164 // 3) Call __tgt_rtl_wait_event to set dependence on the event. Whether the 165 // operation is blocking or non-blocking depends on the target. It is expected 166 // to be non-blocking, just set dependence and return. 167 // 4) Call __tgt_rtl_sync_event to sync the event. It is expected to block the 168 // thread calling the function. 169 // 5) Destroy the event (__tgt_rtl_destroy_event). 170 // { 171 int32_t __tgt_rtl_create_event(int32_t ID, void **Event); 172 173 int32_t __tgt_rtl_record_event(int32_t ID, void *Event, 174 __tgt_async_info *AsyncInfo); 175 176 int32_t __tgt_rtl_wait_event(int32_t ID, void *Event, 177 __tgt_async_info *AsyncInfo); 178 179 int32_t __tgt_rtl_sync_event(int32_t ID, void *Event); 180 181 int32_t __tgt_rtl_destroy_event(int32_t ID, void *Event); 182 // } 183 184 int32_t __tgt_rtl_init_async_info(int32_t ID, __tgt_async_info **AsyncInfoPtr); 185 int32_t __tgt_rtl_init_device_info(int32_t ID, __tgt_device_info *DeviceInfoPtr, 186 const char **ErrStr); 187 188 #ifdef __cplusplus 189 } 190 #endif 191 192 #endif // _OMPTARGETPLUGIN_H_ 193