1 //===-- tsan_interface.h ----------------------------------------*- 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 is a part of ThreadSanitizer (TSan), a race detector. 10 // 11 // Public interface header for TSan. 12 //===----------------------------------------------------------------------===// 13 #ifndef SANITIZER_TSAN_INTERFACE_H 14 #define SANITIZER_TSAN_INTERFACE_H 15 16 #include <sanitizer/common_interface_defs.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 // __tsan_release establishes a happens-before relation with a preceding 23 // __tsan_acquire on the same address. 24 void __tsan_acquire(void *addr); 25 void __tsan_release(void *addr); 26 27 // Annotations for custom mutexes. 28 // The annotations allow to get better reports (with sets of locked mutexes), 29 // detect more types of bugs (e.g. mutex misuses, races between lock/unlock and 30 // destruction and potential deadlocks) and improve precision and performance 31 // (by ignoring individual atomic operations in mutex code). However, the 32 // downside is that annotated mutex code itself is not checked for correctness. 33 34 // Mutex creation flags are passed to __tsan_mutex_create annotation. 35 // If mutex has no constructor and __tsan_mutex_create is not called, 36 // the flags may be passed to __tsan_mutex_pre_lock/__tsan_mutex_post_lock 37 // annotations. 38 39 // Mutex has static storage duration and no-op constructor and destructor. 40 // This effectively makes tsan ignore destroy annotation. 41 static const unsigned __tsan_mutex_linker_init = 1 << 0; 42 // Mutex is write reentrant. 43 static const unsigned __tsan_mutex_write_reentrant = 1 << 1; 44 // Mutex is read reentrant. 45 static const unsigned __tsan_mutex_read_reentrant = 1 << 2; 46 // Mutex does not have static storage duration, and must not be used after 47 // its destructor runs. The opposite of __tsan_mutex_linker_init. 48 // If this flag is passed to __tsan_mutex_destroy, then the destruction 49 // is ignored unless this flag was previously set on the mutex. 50 static const unsigned __tsan_mutex_not_static = 1 << 8; 51 52 // Mutex operation flags: 53 54 // Denotes read lock operation. 55 static const unsigned __tsan_mutex_read_lock = 1 << 3; 56 // Denotes try lock operation. 57 static const unsigned __tsan_mutex_try_lock = 1 << 4; 58 // Denotes that a try lock operation has failed to acquire the mutex. 59 static const unsigned __tsan_mutex_try_lock_failed = 1 << 5; 60 // Denotes that the lock operation acquires multiple recursion levels. 61 // Number of levels is passed in recursion parameter. 62 // This is useful for annotation of e.g. Java builtin monitors, 63 // for which wait operation releases all recursive acquisitions of the mutex. 64 static const unsigned __tsan_mutex_recursive_lock = 1 << 6; 65 // Denotes that the unlock operation releases all recursion levels. 66 // Number of released levels is returned and later must be passed to 67 // the corresponding __tsan_mutex_post_lock annotation. 68 static const unsigned __tsan_mutex_recursive_unlock = 1 << 7; 69 70 // Convenient composed constants. 71 static const unsigned __tsan_mutex_try_read_lock = 72 __tsan_mutex_read_lock | __tsan_mutex_try_lock; 73 static const unsigned __tsan_mutex_try_read_lock_failed = 74 __tsan_mutex_try_read_lock | __tsan_mutex_try_lock_failed; 75 76 // Annotate creation of a mutex. 77 // Supported flags: mutex creation flags. 78 void __tsan_mutex_create(void *addr, unsigned flags); 79 80 // Annotate destruction of a mutex. 81 // Supported flags: 82 // - __tsan_mutex_linker_init 83 // - __tsan_mutex_not_static 84 void __tsan_mutex_destroy(void *addr, unsigned flags); 85 86 // Annotate start of lock operation. 87 // Supported flags: 88 // - __tsan_mutex_read_lock 89 // - __tsan_mutex_try_lock 90 // - all mutex creation flags 91 void __tsan_mutex_pre_lock(void *addr, unsigned flags); 92 93 // Annotate end of lock operation. 94 // Supported flags: 95 // - __tsan_mutex_read_lock (must match __tsan_mutex_pre_lock) 96 // - __tsan_mutex_try_lock (must match __tsan_mutex_pre_lock) 97 // - __tsan_mutex_try_lock_failed 98 // - __tsan_mutex_recursive_lock 99 // - all mutex creation flags 100 void __tsan_mutex_post_lock(void *addr, unsigned flags, int recursion); 101 102 // Annotate start of unlock operation. 103 // Supported flags: 104 // - __tsan_mutex_read_lock 105 // - __tsan_mutex_recursive_unlock 106 int __tsan_mutex_pre_unlock(void *addr, unsigned flags); 107 108 // Annotate end of unlock operation. 109 // Supported flags: 110 // - __tsan_mutex_read_lock (must match __tsan_mutex_pre_unlock) 111 void __tsan_mutex_post_unlock(void *addr, unsigned flags); 112 113 // Annotate start/end of notify/signal/broadcast operation. 114 // Supported flags: none. 115 void __tsan_mutex_pre_signal(void *addr, unsigned flags); 116 void __tsan_mutex_post_signal(void *addr, unsigned flags); 117 118 // Annotate start/end of a region of code where lock/unlock/signal operation 119 // diverts to do something else unrelated to the mutex. This can be used to 120 // annotate, for example, calls into cooperative scheduler or contention 121 // profiling code. 122 // These annotations must be called only from within 123 // __tsan_mutex_pre/post_lock, __tsan_mutex_pre/post_unlock, 124 // __tsan_mutex_pre/post_signal regions. 125 // Supported flags: none. 126 void __tsan_mutex_pre_divert(void *addr, unsigned flags); 127 void __tsan_mutex_post_divert(void *addr, unsigned flags); 128 129 // External race detection API. 130 // Can be used by non-instrumented libraries to detect when their objects are 131 // being used in an unsafe manner. 132 // - __tsan_external_read/__tsan_external_write annotates the logical reads 133 // and writes of the object at the specified address. 'caller_pc' should 134 // be the PC of the library user, which the library can obtain with e.g. 135 // `__builtin_return_address(0)`. 136 // - __tsan_external_register_tag registers a 'tag' with the specified name, 137 // which is later used in read/write annotations to denote the object type 138 // - __tsan_external_assign_tag can optionally mark a heap object with a tag 139 void *__tsan_external_register_tag(const char *object_type); 140 void __tsan_external_register_header(void *tag, const char *header); 141 void __tsan_external_assign_tag(void *addr, void *tag); 142 void __tsan_external_read(void *addr, void *caller_pc, void *tag); 143 void __tsan_external_write(void *addr, void *caller_pc, void *tag); 144 145 // Fiber switching API. 146 // - TSAN context for fiber can be created by __tsan_create_fiber 147 // and freed by __tsan_destroy_fiber. 148 // - TSAN context of current fiber or thread can be obtained 149 // by calling __tsan_get_current_fiber. 150 // - __tsan_switch_to_fiber should be called immediately before switch 151 // to fiber, such as call of swapcontext. 152 // - Fiber name can be set by __tsan_set_fiber_name. 153 void *__tsan_get_current_fiber(void); 154 void *__tsan_create_fiber(unsigned flags); 155 void __tsan_destroy_fiber(void *fiber); 156 void __tsan_switch_to_fiber(void *fiber, unsigned flags); 157 void __tsan_set_fiber_name(void *fiber, const char *name); 158 159 // Flags for __tsan_switch_to_fiber: 160 // Do not establish a happens-before relation between fibers 161 static const unsigned __tsan_switch_to_fiber_no_sync = 1 << 0; 162 163 // User-provided callback invoked on TSan initialization. 164 void __tsan_on_initialize(); 165 166 // User-provided callback invoked on TSan shutdown. 167 // `failed` - Nonzero if TSan did detect issues, zero otherwise. 168 // Return `0` if TSan should exit as if no issues were detected. Return nonzero 169 // if TSan should exit as if issues were detected. 170 int __tsan_on_finalize(int failed); 171 172 // Release TSan internal memory in a best-effort manner. 173 void __tsan_flush_memory(); 174 175 // User-provided default TSAN options. 176 const char* __tsan_default_options(void); 177 178 // User-provided default TSAN suppressions. 179 const char* __tsan_default_suppressions(void); 180 181 /// Returns a report's description. 182 /// 183 /// Returns a report's description (issue type), number of duplicate issues 184 /// found, counts of array data (stack traces, memory operations, locations, 185 /// mutexes, threads, unique thread IDs) and a stack trace of a <c>sleep()</c> 186 /// call (if one was involved in the issue). 187 /// 188 /// \param report Opaque pointer to the current report. 189 /// \param[out] description Report type description. 190 /// \param[out] count Count of duplicate issues. 191 /// \param[out] stack_count Count of stack traces. 192 /// \param[out] mop_count Count of memory operations. 193 /// \param[out] loc_count Count of locations. 194 /// \param[out] mutex_count Count of mutexes. 195 /// \param[out] thread_count Count of threads. 196 /// \param[out] unique_tid_count Count of unique thread IDs. 197 /// \param sleep_trace A buffer to store the stack trace of a <c>sleep()</c> 198 /// call. 199 /// \param trace_size Size in bytes of the trace buffer. 200 /// \returns Returns 1 if successful, 0 if not. 201 int __tsan_get_report_data(void *report, const char **description, int *count, 202 int *stack_count, int *mop_count, int *loc_count, 203 int *mutex_count, int *thread_count, 204 int *unique_tid_count, void **sleep_trace, 205 unsigned long trace_size); 206 207 /// Returns information about stack traces included in the report. 208 /// 209 /// \param report Opaque pointer to the current report. 210 /// \param idx Index to the report's stacks. 211 /// \param trace A buffer to store the stack trace. 212 /// \param trace_size Size in bytes of the trace buffer. 213 /// \returns Returns 1 if successful, 0 if not. 214 int __tsan_get_report_stack(void *report, unsigned long idx, void **trace, 215 unsigned long trace_size); 216 217 /// Returns information about memory operations included in the report. 218 /// 219 /// \param report Opaque pointer to the current report. 220 /// \param idx Index to the report's memory operations. 221 /// \param[out] tid Thread ID of the memory operation. 222 /// \param[out] addr Address of the memory operation. 223 /// \param[out] size Size of the memory operation. 224 /// \param[out] write Write flag of the memory operation. 225 /// \param[out] atomic Atomicity flag of the memory operation. 226 /// \param trace A buffer to store the stack trace. 227 /// \param trace_size Size in bytes of the trace buffer. 228 /// \returns Returns 1 if successful, 0 if not. 229 int __tsan_get_report_mop(void *report, unsigned long idx, int *tid, 230 void **addr, int *size, int *write, int *atomic, 231 void **trace, unsigned long trace_size); 232 233 /// Returns information about locations included in the report. 234 /// 235 /// \param report Opaque pointer to the current report. 236 /// \param idx Index to the report's locations. 237 /// \param[out] type Type of the location. 238 /// \param[out] addr Address of the location. 239 /// \param[out] start Start of the location. 240 /// \param[out] size Size of the location. 241 /// \param[out] tid Thread ID of the location. 242 /// \param[out] fd File descriptor of the location. 243 /// \param[out] suppressable Suppressable flag. 244 /// \param trace A buffer to store the stack trace. 245 /// \param trace_size Size in bytes of the trace buffer. 246 /// \returns Returns 1 if successful, 0 if not. 247 int __tsan_get_report_loc(void *report, unsigned long idx, const char **type, 248 void **addr, void **start, unsigned long *size, 249 int *tid, int *fd, int *suppressable, void **trace, 250 unsigned long trace_size); 251 252 /// Returns information about mutexes included in the report. 253 /// 254 /// \param report Opaque pointer to the current report. 255 /// \param idx Index to the report's mutexes. 256 /// \param[out] mutex_id Id of the mutex. 257 /// \param[out] addr Address of the mutex. 258 /// \param[out] destroyed Destroyed mutex flag. 259 /// \param trace A buffer to store the stack trace. 260 /// \param trace_size Size in bytes of the trace buffer. 261 /// \returns Returns 1 if successful, 0 if not. 262 int __tsan_get_report_mutex(void *report, unsigned long idx, uint64_t *mutex_id, 263 void **addr, int *destroyed, void **trace, 264 unsigned long trace_size); 265 266 /// Returns information about threads included in the report. 267 /// 268 /// \param report Opaque pointer to the current report. 269 /// \param idx Index to the report's threads. 270 /// \param[out] tid Thread ID of the thread. 271 /// \param[out] os_id Operating system's ID of the thread. 272 /// \param[out] running Running flag of the thread. 273 /// \param[out] name Name of the thread. 274 /// \param[out] parent_tid ID of the parent thread. 275 /// \param trace A buffer to store the stack trace. 276 /// \param trace_size Size in bytes of the trace buffer. 277 /// \returns Returns 1 if successful, 0 if not. 278 int __tsan_get_report_thread(void *report, unsigned long idx, int *tid, 279 uint64_t *os_id, int *running, const char **name, 280 int *parent_tid, void **trace, 281 unsigned long trace_size); 282 283 /// Returns information about unique thread IDs included in the report. 284 /// 285 /// \param report Opaque pointer to the current report. 286 /// \param idx Index to the report's unique thread IDs. 287 /// \param[out] tid Unique thread ID of the report. 288 /// \returns Returns 1 if successful, 0 if not. 289 int __tsan_get_report_unique_tid(void *report, unsigned long idx, int *tid); 290 291 /// Returns the current report. 292 /// 293 /// If TSan is currently reporting a detected issue on the current thread, 294 /// returns an opaque pointer to the current report. Otherwise returns NULL. 295 /// \returns An opaque pointer to the current report. Otherwise returns NULL. 296 void *__tsan_get_current_report(); 297 298 #ifdef __cplusplus 299 } // extern "C" 300 #endif 301 302 #endif // SANITIZER_TSAN_INTERFACE_H 303