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