1 // Copyright 2017 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 // This file defines dynamic annotations for use with dynamic analysis tool 16 // such as valgrind, PIN, etc. 17 // 18 // Dynamic annotation is a source code annotation that affects the generated 19 // code (that is, the annotation is not a comment). Each such annotation is 20 // attached to a particular instruction and/or to a particular object (address) 21 // in the program. 22 // 23 // The annotations that should be used by users are macros in all upper-case 24 // (e.g., ANNOTATE_THREAD_NAME). 25 // 26 // Actual implementation of these macros may differ depending on the dynamic 27 // analysis tool being used. 28 // 29 // This file supports the following configurations: 30 // - Dynamic Annotations enabled (with static thread-safety warnings disabled). 31 // In this case, macros expand to functions implemented by Thread Sanitizer, 32 // when building with TSan. When not provided an external implementation, 33 // dynamic_annotations.cc provides no-op implementations. 34 // 35 // - Static Clang thread-safety warnings enabled. 36 // When building with a Clang compiler that supports thread-safety warnings, 37 // a subset of annotations can be statically-checked at compile-time. We 38 // expand these macros to static-inline functions that can be analyzed for 39 // thread-safety, but afterwards elided when building the final binary. 40 // 41 // - All annotations are disabled. 42 // If neither Dynamic Annotations nor Clang thread-safety warnings are 43 // enabled, then all annotation-macros expand to empty. 44 45 #ifndef ABSL_BASE_INTERNAL_DYNAMIC_ANNOTATIONS_H_ 46 #define ABSL_BASE_INTERNAL_DYNAMIC_ANNOTATIONS_H_ 47 48 #include <stddef.h> 49 50 #include "absl/base/config.h" 51 52 // ------------------------------------------------------------------------- 53 // Decide which features are enabled 54 55 #ifndef DYNAMIC_ANNOTATIONS_ENABLED 56 #define DYNAMIC_ANNOTATIONS_ENABLED 0 57 #endif 58 59 #if defined(__clang__) && !defined(SWIG) 60 #define ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED 1 61 #endif 62 63 #if DYNAMIC_ANNOTATIONS_ENABLED != 0 64 65 #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 1 66 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 1 67 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 1 68 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED 0 69 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED 1 70 71 #else 72 73 #define ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 0 74 #define ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 0 75 #define ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 0 76 77 // Clang provides limited support for static thread-safety analysis through a 78 // feature called Annotalysis. We configure macro-definitions according to 79 // whether Annotalysis support is available. When running in opt-mode, GCC 80 // will issue a warning, if these attributes are compiled. Only include them 81 // when compiling using Clang. 82 83 // ANNOTALYSIS_ENABLED == 1 when IGNORE_READ_ATTRIBUTE_ENABLED == 1 84 #define ABSL_INTERNAL_ANNOTALYSIS_ENABLED \ 85 defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 86 // Read/write annotations are enabled in Annotalysis mode; disabled otherwise. 87 #define ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED \ 88 ABSL_INTERNAL_ANNOTALYSIS_ENABLED 89 #endif 90 91 // Memory annotations are also made available to LLVM's Memory Sanitizer 92 #if defined(ABSL_HAVE_MEMORY_SANITIZER) && !defined(__native_client__) 93 #define ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED 1 94 #endif 95 96 #ifndef ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED 97 #define ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED 0 98 #endif 99 100 #ifdef __cplusplus 101 #define ABSL_INTERNAL_BEGIN_EXTERN_C extern "C" { 102 #define ABSL_INTERNAL_END_EXTERN_C } // extern "C" 103 #define ABSL_INTERNAL_GLOBAL_SCOPED(F) ::F 104 #define ABSL_INTERNAL_STATIC_INLINE inline 105 #else 106 #define ABSL_INTERNAL_BEGIN_EXTERN_C // empty 107 #define ABSL_INTERNAL_END_EXTERN_C // empty 108 #define ABSL_INTERNAL_GLOBAL_SCOPED(F) F 109 #define ABSL_INTERNAL_STATIC_INLINE static inline 110 #endif 111 112 // ------------------------------------------------------------------------- 113 // Define race annotations. 114 115 #if ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 1 116 117 // ------------------------------------------------------------- 118 // Annotations that suppress errors. It is usually better to express the 119 // program's synchronization using the other annotations, but these can be used 120 // when all else fails. 121 122 // Report that we may have a benign race at `pointer`, with size 123 // "sizeof(*(pointer))". `pointer` must be a non-void* pointer. Insert at the 124 // point where `pointer` has been allocated, preferably close to the point 125 // where the race happens. See also ANNOTATE_BENIGN_RACE_STATIC. 126 #define ANNOTATE_BENIGN_RACE(pointer, description) \ 127 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \ 128 (__FILE__, __LINE__, pointer, sizeof(*(pointer)), description) 129 130 // Same as ANNOTATE_BENIGN_RACE(`address`, `description`), but applies to 131 // the memory range [`address`, `address`+`size`). 132 #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \ 133 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateBenignRaceSized) \ 134 (__FILE__, __LINE__, address, size, description) 135 136 // Enable (`enable`!=0) or disable (`enable`==0) race detection for all threads. 137 // This annotation could be useful if you want to skip expensive race analysis 138 // during some period of program execution, e.g. during initialization. 139 #define ANNOTATE_ENABLE_RACE_DETECTION(enable) \ 140 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateEnableRaceDetection) \ 141 (__FILE__, __LINE__, enable) 142 143 // ------------------------------------------------------------- 144 // Annotations useful for debugging. 145 146 // Report the current thread `name` to a race detector. 147 #define ANNOTATE_THREAD_NAME(name) \ 148 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateThreadName)(__FILE__, __LINE__, name) 149 150 // ------------------------------------------------------------- 151 // Annotations useful when implementing locks. They are not normally needed by 152 // modules that merely use locks. The `lock` argument is a pointer to the lock 153 // object. 154 155 // Report that a lock has been created at address `lock`. 156 #define ANNOTATE_RWLOCK_CREATE(lock) \ 157 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreate)(__FILE__, __LINE__, lock) 158 159 // Report that a linker initialized lock has been created at address `lock`. 160 #ifdef ABSL_HAVE_THREAD_SANITIZER 161 #define ANNOTATE_RWLOCK_CREATE_STATIC(lock) \ 162 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockCreateStatic) \ 163 (__FILE__, __LINE__, lock) 164 #else 165 #define ANNOTATE_RWLOCK_CREATE_STATIC(lock) ANNOTATE_RWLOCK_CREATE(lock) 166 #endif 167 168 // Report that the lock at address `lock` is about to be destroyed. 169 #define ANNOTATE_RWLOCK_DESTROY(lock) \ 170 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockDestroy)(__FILE__, __LINE__, lock) 171 172 // Report that the lock at address `lock` has been acquired. 173 // `is_w`=1 for writer lock, `is_w`=0 for reader lock. 174 #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \ 175 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockAcquired) \ 176 (__FILE__, __LINE__, lock, is_w) 177 178 // Report that the lock at address `lock` is about to be released. 179 // `is_w`=1 for writer lock, `is_w`=0 for reader lock. 180 #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ 181 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateRWLockReleased) \ 182 (__FILE__, __LINE__, lock, is_w) 183 184 // Apply ANNOTATE_BENIGN_RACE_SIZED to a static variable `static_var`. 185 #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \ 186 namespace { \ 187 class static_var##_annotator { \ 188 public: \ 189 static_var##_annotator() { \ 190 ANNOTATE_BENIGN_RACE_SIZED(&static_var, sizeof(static_var), \ 191 #static_var ": " description); \ 192 } \ 193 }; \ 194 static static_var##_annotator the##static_var##_annotator; \ 195 } // namespace 196 197 #else // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED == 0 198 199 #define ANNOTATE_RWLOCK_CREATE(lock) // empty 200 #define ANNOTATE_RWLOCK_CREATE_STATIC(lock) // empty 201 #define ANNOTATE_RWLOCK_DESTROY(lock) // empty 202 #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) // empty 203 #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) // empty 204 #define ANNOTATE_BENIGN_RACE(address, description) // empty 205 #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) // empty 206 #define ANNOTATE_THREAD_NAME(name) // empty 207 #define ANNOTATE_ENABLE_RACE_DETECTION(enable) // empty 208 #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description) // empty 209 210 #endif // ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 211 212 // ------------------------------------------------------------------------- 213 // Define memory annotations. 214 215 #if ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED == 1 216 217 #include <sanitizer/msan_interface.h> 218 219 #define ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \ 220 __msan_unpoison(address, size) 221 222 #define ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \ 223 __msan_allocated_memory(address, size) 224 225 #else // ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED == 0 226 227 #if DYNAMIC_ANNOTATIONS_ENABLED == 1 228 #define ANNOTATE_MEMORY_IS_INITIALIZED(address, size) \ 229 do { \ 230 (void)(address); \ 231 (void)(size); \ 232 } while (0) 233 #define ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) \ 234 do { \ 235 (void)(address); \ 236 (void)(size); \ 237 } while (0) 238 #else 239 #define ANNOTATE_MEMORY_IS_INITIALIZED(address, size) // empty 240 #define ANNOTATE_MEMORY_IS_UNINITIALIZED(address, size) // empty 241 #endif 242 243 #endif // ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED 244 245 // ------------------------------------------------------------------------- 246 // Define IGNORE_READS_BEGIN/_END attributes. 247 248 #if defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 249 250 #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE \ 251 __attribute((exclusive_lock_function("*"))) 252 #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE \ 253 __attribute((unlock_function("*"))) 254 255 #else // !defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 256 257 #define ABSL_INTERNAL_IGNORE_READS_BEGIN_ATTRIBUTE // empty 258 #define ABSL_INTERNAL_IGNORE_READS_END_ATTRIBUTE // empty 259 260 #endif // defined(ABSL_INTERNAL_IGNORE_READS_ATTRIBUTE_ENABLED) 261 262 // ------------------------------------------------------------------------- 263 // Define IGNORE_READS_BEGIN/_END annotations. 264 265 #if ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED == 1 266 267 // Request the analysis tool to ignore all reads in the current thread until 268 // ANNOTATE_IGNORE_READS_END is called. Useful to ignore intentional racey 269 // reads, while still checking other reads and all writes. 270 // See also ANNOTATE_UNPROTECTED_READ. 271 #define ANNOTATE_IGNORE_READS_BEGIN() \ 272 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsBegin)(__FILE__, __LINE__) 273 274 // Stop ignoring reads. 275 #define ANNOTATE_IGNORE_READS_END() \ 276 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreReadsEnd)(__FILE__, __LINE__) 277 278 #elif defined(ABSL_INTERNAL_ANNOTALYSIS_ENABLED) 279 280 // When Annotalysis is enabled without Dynamic Annotations, the use of 281 // static-inline functions allows the annotations to be read at compile-time, 282 // while still letting the compiler elide the functions from the final build. 283 // 284 // TODO(delesley) -- The exclusive lock here ignores writes as well, but 285 // allows IGNORE_READS_AND_WRITES to work properly. 286 287 #define ANNOTATE_IGNORE_READS_BEGIN() \ 288 ABSL_INTERNAL_GLOBAL_SCOPED(AbslInternalAnnotateIgnoreReadsBegin)() 289 290 #define ANNOTATE_IGNORE_READS_END() \ 291 ABSL_INTERNAL_GLOBAL_SCOPED(AbslInternalAnnotateIgnoreReadsEnd)() 292 293 #else 294 295 #define ANNOTATE_IGNORE_READS_BEGIN() // empty 296 #define ANNOTATE_IGNORE_READS_END() // empty 297 298 #endif 299 300 // ------------------------------------------------------------------------- 301 // Define IGNORE_WRITES_BEGIN/_END annotations. 302 303 #if ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED == 1 304 305 // Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore writes instead. 306 #define ANNOTATE_IGNORE_WRITES_BEGIN() \ 307 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesBegin)(__FILE__, __LINE__) 308 309 // Stop ignoring writes. 310 #define ANNOTATE_IGNORE_WRITES_END() \ 311 ABSL_INTERNAL_GLOBAL_SCOPED(AnnotateIgnoreWritesEnd)(__FILE__, __LINE__) 312 313 #else 314 315 #define ANNOTATE_IGNORE_WRITES_BEGIN() // empty 316 #define ANNOTATE_IGNORE_WRITES_END() // empty 317 318 #endif 319 320 // ------------------------------------------------------------------------- 321 // Define the ANNOTATE_IGNORE_READS_AND_WRITES_* annotations using the more 322 // primitive annotations defined above. 323 // 324 // Instead of doing 325 // ANNOTATE_IGNORE_READS_BEGIN(); 326 // ... = x; 327 // ANNOTATE_IGNORE_READS_END(); 328 // one can use 329 // ... = ANNOTATE_UNPROTECTED_READ(x); 330 331 #if defined(ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED) 332 333 // Start ignoring all memory accesses (both reads and writes). 334 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \ 335 do { \ 336 ANNOTATE_IGNORE_READS_BEGIN(); \ 337 ANNOTATE_IGNORE_WRITES_BEGIN(); \ 338 } while (0) 339 340 // Stop ignoring both reads and writes. 341 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \ 342 do { \ 343 ANNOTATE_IGNORE_WRITES_END(); \ 344 ANNOTATE_IGNORE_READS_END(); \ 345 } while (0) 346 347 #ifdef __cplusplus 348 // ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racey reads. 349 #define ANNOTATE_UNPROTECTED_READ(x) \ 350 absl::base_internal::AnnotateUnprotectedRead(x) 351 352 #endif 353 354 #else 355 356 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() // empty 357 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() // empty 358 #define ANNOTATE_UNPROTECTED_READ(x) (x) 359 360 #endif 361 362 // ------------------------------------------------------------------------- 363 // Address sanitizer annotations 364 365 #ifdef ABSL_HAVE_ADDRESS_SANITIZER 366 // Describe the current state of a contiguous container such as e.g. 367 // std::vector or std::string. For more details see 368 // sanitizer/common_interface_defs.h, which is provided by the compiler. 369 #include <sanitizer/common_interface_defs.h> 370 371 #define ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) \ 372 __sanitizer_annotate_contiguous_container(beg, end, old_mid, new_mid) 373 #define ADDRESS_SANITIZER_REDZONE(name) \ 374 struct { \ 375 char x[8] __attribute__((aligned(8))); \ 376 } name 377 378 #else 379 380 #define ANNOTATE_CONTIGUOUS_CONTAINER(beg, end, old_mid, new_mid) 381 #define ADDRESS_SANITIZER_REDZONE(name) static_assert(true, "") 382 383 #endif // ABSL_HAVE_ADDRESS_SANITIZER 384 385 // ------------------------------------------------------------------------- 386 // Undefine the macros intended only for this file. 387 388 #undef ABSL_INTERNAL_RACE_ANNOTATIONS_ENABLED 389 #undef ABSL_INTERNAL_MEMORY_ANNOTATIONS_ENABLED 390 #undef ABSL_INTERNAL_READS_ANNOTATIONS_ENABLED 391 #undef ABSL_INTERNAL_WRITES_ANNOTATIONS_ENABLED 392 #undef ABSL_INTERNAL_ANNOTALYSIS_ENABLED 393 #undef ABSL_INTERNAL_READS_WRITES_ANNOTATIONS_ENABLED 394 #undef ABSL_INTERNAL_BEGIN_EXTERN_C 395 #undef ABSL_INTERNAL_END_EXTERN_C 396 #undef ABSL_INTERNAL_STATIC_INLINE 397 398 #endif // ABSL_BASE_INTERNAL_DYNAMIC_ANNOTATIONS_H_ 399