1 /*===-------------------------------------------------------------------------- 2 * ATMI (Asynchronous Task and Memory Interface) 3 * 4 * This file is distributed under the MIT License. See LICENSE.txt for details. 5 *===------------------------------------------------------------------------*/ 6 #ifndef INCLUDE_ATMI_RUNTIME_H_ 7 #define INCLUDE_ATMI_RUNTIME_H_ 8 9 #include "atmi.h" 10 #include "hsa.h" 11 #include <inttypes.h> 12 #include <stdlib.h> 13 #ifndef __cplusplus 14 #include <stdbool.h> 15 #endif 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /** \defgroup context_functions ATMI Context Setup and Finalize 22 * @{ 23 */ 24 /** 25 * @brief Initialize the ATMI runtime environment. 26 * 27 * @detal All ATMI runtime functions will fail if this function is not called 28 * at least once. The user may initialize difference device types at different 29 * regions in the program in order for optimization purposes. 30 * 31 * @retval ::ATMI_STATUS_SUCCESS The function has executed successfully. 32 * 33 * @retval ::ATMI_STATUS_ERROR The function encountered errors. 34 * 35 * @retval ::ATMI_STATUS_UNKNOWN The function encountered errors. 36 */ 37 atmi_status_t atmi_init(); 38 39 /** 40 * @brief Finalize the ATMI runtime environment. 41 * 42 * @detail ATMI runtime functions will fail if called after finalize. 43 * 44 * @retval ::ATMI_STATUS_SUCCESS The function has executed successfully. 45 * 46 * @retval ::ATMI_STATUS_ERROR The function encountered errors. 47 * 48 * @retval ::ATMI_STATUS_UNKNOWN The function encountered errors. 49 */ 50 atmi_status_t atmi_finalize(); 51 /** @} */ 52 53 /** \defgroup module_functions ATMI Module 54 * @{ 55 */ 56 57 /** 58 * @brief Register the ATMI code module from memory on to a specific place 59 * (device). 60 * 61 * @detail Currently, only GPU devices need explicit module registration because 62 * of their specific ISAs that require a separate compilation phase. On the 63 * other 64 * hand, CPU devices execute regular x86 functions that are compiled with the 65 * host program. 66 * 67 * @param[in] module_bytes A memory region that contains the GPU modules 68 * targeting ::AMDGCN platform types. Value cannot be NULL. 69 * 70 * @param[in] module_size Size of module region 71 * 72 * @param[in] place Denotes the execution place (device) on which the module 73 * should be registered and loaded. 74 * 75 * @param[in] on_deserialized_data Callback run on deserialized code object, 76 * before loading it 77 * 78 * @param[in] cb_state void* passed to on_deserialized_data callback 79 * 80 * @retval ::ATMI_STATUS_SUCCESS The function has executed successfully. 81 * 82 * @retval ::ATMI_STATUS_ERROR The function encountered errors. 83 * 84 * @retval ::ATMI_STATUS_UNKNOWN The function encountered errors. 85 * 86 */ 87 atmi_status_t atmi_module_register_from_memory_to_place( 88 void *module_bytes, size_t module_size, atmi_place_t place, 89 atmi_status_t (*on_deserialized_data)(void *data, size_t size, 90 void *cb_state), 91 void *cb_state); 92 93 /** @} */ 94 95 /** \defgroup machine ATMI Machine 96 * @{ 97 */ 98 /** 99 * @brief ATMI's device discovery function to get the current machine's 100 * topology. 101 * 102 * @detail The @p atmi_machine_t structure is a tree-based representation of the 103 * compute and memory elements in the current node. Once ATMI is initialized, 104 * this function can be called to retrieve the pointer to this global structure. 105 * 106 * @return Returns a pointer to a global structure of tyoe @p atmi_machine_t. 107 * Returns NULL if ATMI is not initialized. 108 */ 109 atmi_machine_t *atmi_machine_get_info(); 110 /** @} */ 111 112 /** \defgroup memory_functions ATMI Data Management 113 * @{ 114 */ 115 /** 116 * @brief Allocate memory from the specified memory place. 117 * 118 * @detail This function allocates memory from the specified memory place. If 119 * the memory 120 * place belongs primarily to the CPU, then the memory will be accessible by 121 * other GPUs and CPUs in the system. If the memory place belongs primarily to a 122 * GPU, 123 * then it cannot be accessed by other devices in the system. 124 * 125 * @param[in] ptr The pointer to the memory that will be allocated. 126 * 127 * @param[in] size The size of the allocation in bytes. 128 * 129 * @param[in] place The memory place in the system to perform the allocation. 130 * 131 * @retval ::ATMI_STATUS_SUCCESS The function has executed successfully. 132 * 133 * @retval ::ATMI_STATUS_ERROR The function encountered errors. 134 * 135 * @retval ::ATMI_STATUS_UNKNOWN The function encountered errors. 136 * 137 */ 138 atmi_status_t atmi_malloc(void **ptr, size_t size, atmi_mem_place_t place); 139 140 /** 141 * @brief Frees memory that was previously allocated. 142 * 143 * @detail This function frees memory that was previously allocated by calling 144 * @p atmi_malloc. It throws an error otherwise. It is illegal to access a 145 * pointer after a call to this function. 146 * 147 * @param[in] ptr The pointer to the memory that has to be freed. 148 * 149 * @retval ::ATMI_STATUS_SUCCESS The function has executed successfully. 150 * 151 * @retval ::ATMI_STATUS_ERROR The function encountered errors. 152 * 153 * @retval ::ATMI_STATUS_UNKNOWN The function encountered errors. 154 * 155 */ 156 atmi_status_t atmi_free(void *ptr); 157 158 atmi_status_t atmi_memcpy_h2d(hsa_signal_t signal, void *deviceDest, 159 const void *hostSrc, size_t size, 160 hsa_agent_t agent); 161 162 atmi_status_t atmi_memcpy_d2h(hsa_signal_t sig, void *hostDest, 163 const void *deviceSrc, size_t size, 164 hsa_agent_t agent); 165 166 /** @} */ 167 168 #ifdef __cplusplus 169 } 170 #endif 171 172 #endif // INCLUDE_ATMI_RUNTIME_H_ 173