1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2021 Mellanox Technologies, Ltd 3 * Copyright (C) 2022 Microsoft Corporation 4 */ 5 6 #include <stdint.h> 7 8 #include <rte_os.h> 9 #include <rte_compat.h> 10 11 #ifndef _RTE_THREAD_H_ 12 #define _RTE_THREAD_H_ 13 14 /** 15 * @file 16 * 17 * Threading functions 18 * 19 * Simple threads functionality supplied by EAL. 20 */ 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /** 27 * Thread id descriptor. 28 */ 29 typedef struct { 30 uintptr_t opaque_id; /**< thread identifier */ 31 } rte_thread_t; 32 33 /** 34 * Thread priority values. 35 */ 36 enum rte_thread_priority { 37 RTE_THREAD_PRIORITY_NORMAL = 0, 38 /**< normal thread priority, the default */ 39 RTE_THREAD_PRIORITY_REALTIME_CRITICAL = 1, 40 /**< highest thread priority allowed */ 41 }; 42 43 /** 44 * TLS key type, an opaque pointer. 45 */ 46 typedef struct eal_tls_key *rte_thread_key; 47 48 /** 49 * @warning 50 * @b EXPERIMENTAL: this API may change without prior notice. 51 * 52 * Get the id of the calling thread. 53 * 54 * @return 55 * Return the thread id of the calling thread. 56 */ 57 __rte_experimental 58 rte_thread_t rte_thread_self(void); 59 60 #ifdef RTE_HAS_CPUSET 61 62 /** 63 * @warning 64 * @b EXPERIMENTAL: this API may change without prior notice. 65 * 66 * Set the affinity of thread 'thread_id' to the cpu set 67 * specified by 'cpuset'. 68 * 69 * @param thread_id 70 * Id of the thread for which to set the affinity. 71 * 72 * @param cpuset 73 * Pointer to CPU affinity to set. 74 * 75 * @return 76 * On success, return 0. 77 * On failure, return a positive errno-style error number. 78 */ 79 __rte_experimental 80 int rte_thread_set_affinity_by_id(rte_thread_t thread_id, 81 const rte_cpuset_t *cpuset); 82 83 /** 84 * @warning 85 * @b EXPERIMENTAL: this API may change without prior notice. 86 * 87 * Get the affinity of thread 'thread_id' and store it 88 * in 'cpuset'. 89 * 90 * @param thread_id 91 * Id of the thread for which to get the affinity. 92 * 93 * @param cpuset 94 * Pointer for storing the affinity value. 95 * 96 * @return 97 * On success, return 0. 98 * On failure, return a positive errno-style error number. 99 */ 100 __rte_experimental 101 int rte_thread_get_affinity_by_id(rte_thread_t thread_id, 102 rte_cpuset_t *cpuset); 103 104 /** 105 * Set core affinity of the current thread. 106 * Support both EAL and non-EAL thread and update TLS. 107 * 108 * @param cpusetp 109 * Pointer to CPU affinity to set. 110 * @return 111 * On success, return 0; otherwise return -1; 112 */ 113 int rte_thread_set_affinity(rte_cpuset_t *cpusetp); 114 115 /** 116 * Get core affinity of the current thread. 117 * 118 * @param cpusetp 119 * Pointer to CPU affinity of current thread. 120 * It presumes input is not NULL, otherwise it causes panic. 121 * 122 */ 123 void rte_thread_get_affinity(rte_cpuset_t *cpusetp); 124 125 #endif /* RTE_HAS_CPUSET */ 126 127 /** 128 * @warning 129 * @b EXPERIMENTAL: this API may change without prior notice. 130 * 131 * Get the priority of a thread. 132 * 133 * @param thread_id 134 * Id of the thread for which to get priority. 135 * 136 * @param priority 137 * Location to store the retrieved priority. 138 * 139 * @return 140 * On success, return 0. 141 * On failure, return a positive errno-style error number. 142 */ 143 __rte_experimental 144 int rte_thread_get_priority(rte_thread_t thread_id, 145 enum rte_thread_priority *priority); 146 147 /** 148 * @warning 149 * @b EXPERIMENTAL: this API may change without prior notice. 150 * 151 * Set the priority of a thread. 152 * 153 * @param thread_id 154 * Id of the thread for which to set priority. 155 * 156 * @param priority 157 * Priority value to be set. 158 * 159 * @return 160 * On success, return 0. 161 * On failure, return a positive errno-style error number. 162 */ 163 __rte_experimental 164 int rte_thread_set_priority(rte_thread_t thread_id, 165 enum rte_thread_priority priority); 166 167 /** 168 * Create a TLS data key visible to all threads in the process. 169 * the created key is later used to get/set a value. 170 * and optional destructor can be set to be called when a thread exits. 171 * 172 * @param key 173 * Pointer to store the allocated key. 174 * @param destructor 175 * The function to be called when the thread exits. 176 * Ignored on Windows OS. 177 * 178 * @return 179 * On success, zero. 180 * On failure, a negative number and an error number is set in rte_errno. 181 * rte_errno can be: ENOMEM - Memory allocation error. 182 * ENOEXEC - Specific OS error. 183 */ 184 185 __rte_experimental 186 int rte_thread_key_create(rte_thread_key *key, 187 void (*destructor)(void *)); 188 189 /** 190 * Delete a TLS data key visible to all threads in the process. 191 * 192 * @param key 193 * The key allocated by rte_thread_key_create(). 194 * 195 * @return 196 * On success, zero. 197 * On failure, a negative number and an error number is set in rte_errno. 198 * rte_errno can be: EINVAL - Invalid parameter passed. 199 * ENOEXEC - Specific OS error. 200 */ 201 __rte_experimental 202 int rte_thread_key_delete(rte_thread_key key); 203 204 /** 205 * Set value bound to the TLS key on behalf of the calling thread. 206 * 207 * @param key 208 * The key allocated by rte_thread_key_create(). 209 * @param value 210 * The value bound to the rte_thread_key key for the calling thread. 211 * 212 * @return 213 * On success, zero. 214 * On failure, a negative number and an error number is set in rte_errno. 215 * rte_errno can be: EINVAL - Invalid parameter passed. 216 * ENOEXEC - Specific OS error. 217 */ 218 __rte_experimental 219 int rte_thread_value_set(rte_thread_key key, const void *value); 220 221 /** 222 * Get value bound to the TLS key on behalf of the calling thread. 223 * 224 * @param key 225 * The key allocated by rte_thread_key_create(). 226 * 227 * @return 228 * On success, value data pointer (can also be NULL). 229 * On failure, NULL and an error number is set in rte_errno. 230 * rte_errno can be: EINVAL - Invalid parameter passed. 231 * ENOEXEC - Specific OS error. 232 */ 233 __rte_experimental 234 void *rte_thread_value_get(rte_thread_key key); 235 236 #ifdef __cplusplus 237 } 238 #endif 239 240 #endif /* _RTE_THREAD_H_ */ 241