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 // Return an integer other than zero if the data can be exchaned from SrcDevId 35 // to DstDevId. If it is data exchangable, the device plugin should provide 36 // function to move data from source device to destination device directly. 37 int32_t __tgt_rtl_is_data_exchangable(int32_t SrcDevId, int32_t DstDevId); 38 39 // Initialize the requires flags for the device. 40 int64_t __tgt_rtl_init_requires(int64_t RequiresFlags); 41 42 // Initialize the specified device. In case of success return 0; otherwise 43 // return an error code. 44 int32_t __tgt_rtl_init_device(int32_t ID); 45 46 // Pass an executable image section described by image to the specified 47 // device and prepare an address table of target entities. In case of error, 48 // return NULL. Otherwise, return a pointer to the built address table. 49 // Individual entries in the table may also be NULL, when the corresponding 50 // offload region is not supported on the target device. 51 __tgt_target_table *__tgt_rtl_load_binary(int32_t ID, 52 __tgt_device_image *Image); 53 54 // Allocate data on the particular target device, of the specified size. 55 // HostPtr is a address of the host data the allocated target data 56 // will be associated with (HostPtr may be NULL if it is not known at 57 // allocation time, like for example it would be for target data that 58 // is allocated by omp_target_alloc() API). Return address of the 59 // allocated data on the target that will be used by libomptarget.so to 60 // initialize the target data mapping structures. These addresses are 61 // used to generate a table of target variables to pass to 62 // __tgt_rtl_run_region(). The __tgt_rtl_data_alloc() returns NULL in 63 // case an error occurred on the target device. 64 void *__tgt_rtl_data_alloc(int32_t ID, int64_t Size, void *HostPtr); 65 66 // Pass the data content to the target device using the target address. In case 67 // of success, return zero. Otherwise, return an error code. 68 int32_t __tgt_rtl_data_submit(int32_t ID, void *TargetPtr, void *HostPtr, 69 int64_t Size); 70 71 int32_t __tgt_rtl_data_submit_async(int32_t ID, void *TargetPtr, void *HostPtr, 72 int64_t Size, 73 __tgt_async_info *AsyncInfoPtr); 74 75 // Retrieve the data content from the target device using its address. In case 76 // of success, return zero. Otherwise, return an error code. 77 int32_t __tgt_rtl_data_retrieve(int32_t ID, void *HostPtr, void *TargetPtr, 78 int64_t Size); 79 80 // Asynchronous version of __tgt_rtl_data_retrieve 81 int32_t __tgt_rtl_data_retrieve_async(int32_t ID, void *HostPtr, 82 void *TargetPtr, int64_t Size, 83 __tgt_async_info *AsyncInfoPtr); 84 85 // Copy the data content from one target device to another target device using 86 // its address. This operation does not need to copy data back to host and then 87 // from host to another device. In case of success, return zero. Otherwise, 88 // return an error code. 89 int32_t __tgt_rtl_data_exchange(int32_t SrcID, void *SrcPtr, int32_t DstID, 90 void *DstPtr, int64_t Size); 91 92 // Asynchronous version of __tgt_rtl_data_exchange 93 int32_t __tgt_rtl_data_exchange_async(int32_t SrcID, void *SrcPtr, 94 int32_t DesID, void *DstPtr, int64_t Size, 95 __tgt_async_info *AsyncInfoPtr); 96 97 // De-allocate the data referenced by target ptr on the device. In case of 98 // success, return zero. Otherwise, return an error code. 99 int32_t __tgt_rtl_data_delete(int32_t ID, void *TargetPtr); 100 101 // Transfer control to the offloaded entry Entry on the target device. 102 // Args and Offsets are arrays of NumArgs size of target addresses and 103 // offsets. An offset should be added to the target address before passing it 104 // to the outlined function on device side. If AsyncInfoPtr is nullptr, it is 105 // synchronous; otherwise it is asynchronous. However, AsyncInfoPtr may be 106 // ignored on some platforms, like x86_64. In that case, it is synchronous. In 107 // case of success, return zero. Otherwise, return an error code. 108 int32_t __tgt_rtl_run_target_region(int32_t ID, void *Entry, void **Args, 109 ptrdiff_t *Offsets, int32_t NumArgs); 110 111 // Asynchronous version of __tgt_rtl_run_target_region 112 int32_t __tgt_rtl_run_target_region_async(int32_t ID, void *Entry, void **Args, 113 ptrdiff_t *Offsets, int32_t NumArgs, 114 __tgt_async_info *AsyncInfoPtr); 115 116 // Similar to __tgt_rtl_run_target_region, but additionally specify the 117 // number of teams to be created and a number of threads in each team. If 118 // AsyncInfoPtr is nullptr, it is synchronous; otherwise it is asynchronous. 119 // However, AsyncInfoPtr may be ignored on some platforms, like x86_64. In that 120 // case, it is synchronous. 121 int32_t __tgt_rtl_run_target_team_region(int32_t ID, void *Entry, void **Args, 122 ptrdiff_t *Offsets, int32_t NumArgs, 123 int32_t NumTeams, int32_t ThreadLimit, 124 uint64_t loop_tripcount); 125 126 // Asynchronous version of __tgt_rtl_run_target_team_region 127 int32_t __tgt_rtl_run_target_team_region_async( 128 int32_t ID, void *Entry, void **Args, ptrdiff_t *Offsets, int32_t NumArgs, 129 int32_t NumTeams, int32_t ThreadLimit, uint64_t loop_tripcount, 130 __tgt_async_info *AsyncInfoPtr); 131 132 // Device synchronization. In case of success, return zero. Otherwise, return an 133 // error code. 134 int32_t __tgt_rtl_synchronize(int32_t ID, __tgt_async_info *AsyncInfoPtr); 135 136 #ifdef __cplusplus 137 } 138 #endif 139 140 #endif // _OMPTARGETPLUGIN_H_ 141