1 /* -*- mode: C; c-basic-offset: 3; -*- */
2
3 /*
4 ----------------------------------------------------------------
5
6 Notice that the following BSD-style license applies to this one
7 file (drd.h) only. The rest of Valgrind is licensed under the
8 terms of the GNU General Public License, version 2, unless
9 otherwise indicated. See the COPYING file in the source
10 distribution for details.
11
12 ----------------------------------------------------------------
13
14 This file is part of DRD, a Valgrind tool for verification of
15 multithreaded programs.
16
17 Copyright (C) 2006-2010 Bart Van Assche <bvanassche@acm.org>.
18 All rights reserved.
19
20 Redistribution and use in source and binary forms, with or without
21 modification, are permitted provided that the following conditions
22 are met:
23
24 1. Redistributions of source code must retain the above copyright
25 notice, this list of conditions and the following disclaimer.
26
27 2. The origin of this software must not be misrepresented; you must
28 not claim that you wrote the original software. If you use this
29 software in a product, an acknowledgment in the product
30 documentation would be appreciated but is not required.
31
32 3. Altered source versions must be plainly marked as such, and must
33 not be misrepresented as being the original software.
34
35 4. The name of the author may not be used to endorse or promote
36 products derived from this software without specific prior written
37 permission.
38
39 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
40 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
41 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
42 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
43 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
45 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
46 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
47 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
48 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
49 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
50
51 ----------------------------------------------------------------
52
53 Notice that the above BSD-style license applies to this one file
54 (drd.h) only. The entire rest of Valgrind is licensed under
55 the terms of the GNU General Public License, version 2. See the
56 COPYING file in the source distribution for details.
57
58 ----------------------------------------------------------------
59 */
60
61 #ifndef __VALGRIND_DRD_H
62 #define __VALGRIND_DRD_H
63
64
65 #include "valgrind.h"
66
67
68 /** Obtain the thread ID assigned by Valgrind's core. */
69 #define DRD_GET_VALGRIND_THREADID \
70 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_GET_VALGRIND_THREAD_ID, \
71 0, 0, 0, 0, 0)
72
73 /** Obtain the thread ID assigned by DRD. */
74 #define DRD_GET_DRD_THREADID \
75 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_GET_DRD_THREAD_ID, \
76 0, 0, 0, 0, 0)
77
78
79 /** Tell DRD not to complain about data races for the specified variable. */
80 #define DRD_IGNORE_VAR(x) ANNOTATE_BENIGN_RACE_SIZED(&(x), sizeof(x), "")
81
82 /** Tell DRD to no longer ignore data races for the specified variable. */
83 #define DRD_STOP_IGNORING_VAR(x) \
84 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_FINISH_SUPPRESSION, \
85 &(x), sizeof(x), 0, 0, 0)
86
87 /**
88 * Tell DRD to trace all memory accesses on the specified variable.
89 * until the memory that was allocated for the variable is freed.
90 */
91 #define DRD_TRACE_VAR(x) \
92 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_START_TRACE_ADDR, \
93 &(x), sizeof(x), 0, 0, 0)
94
95 /**
96 * @defgroup RaceDetectionAnnotations Data race detection annotations.
97 *
98 * @see See also the source file <a href="http://code.google.com/p/data-race-test/source/browse/trunk/dynamic_annotations/dynamic_annotations.h</a>
99
100 * in the ThreadSanitizer project.
101 */
102 /*@{*/
103
104 /**
105 * Tell DRD to insert a happens-before mark. addr is the address of an object
106 * that is not a pthread synchronization object.
107 */
108 #define ANNOTATE_HAPPENS_BEFORE(addr) \
109 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, \
110 VG_USERREQ__DRD_ANNOTATE_HAPPENS_BEFORE, \
111 addr, 0, 0, 0, 0)
112
113 /**
114 * Tell DRD that the memory accesses executed after this annotation will
115 * happen after all memory accesses performed before all preceding
116 * ANNOTATE_HAPPENS_BEFORE(addr). addr is the address of an object that is not
117 * a pthread synchronization object. Inserting a happens-after annotation
118 * before any other thread has passed by a happens-before annotation for the
119 * same address is an error.
120 */
121 #define ANNOTATE_HAPPENS_AFTER(addr) \
122 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, \
123 VG_USERREQ__DRD_ANNOTATE_HAPPENS_AFTER, \
124 addr, 0, 0, 0, 0)
125
126 /**
127 * Tell DRD that waiting on the condition variable at address cv has succeeded
128 * and a lock on the mutex at address mtx is now held. Since DRD always inserts
129 * a happens before relation between the pthread_cond_signal() or
130 * pthread_cond_broadcast() call that wakes up a pthread_cond_wait() or
131 * pthread_cond_timedwait() call and the woken up thread, this macro has been
132 * defined such that it has no effect.
133 */
134 #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, mtx) do { } while(0)
135
136 /**
137 * Tell DRD that the condition variable at address cv is about to be signaled.
138 */
139 #define ANNOTATE_CONDVAR_SIGNAL(cv) do { } while(0)
140
141 /**
142 * Tell DRD that the condition variable at address cv is about to be signaled.
143 */
144 #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) do { } while(0)
145
146 /**
147 * Tell DRD that waiting on condition variable at address cv succeeded and that
148 * the memory operations performed after this annotation should be considered
149 * to happen after the matching ANNOTATE_CONDVAR_SIGNAL(cv). Since this is the
150 * default behavior of DRD, this macro and the macro above have been defined
151 * such that they have no effect.
152 */
153 #define ANNOTATE_CONDVAR_WAIT(cv) do { } while(0)
154
155 /**
156 * Tell DRD to consider the memory operations that happened before a mutex
157 * unlock event and after the subsequent mutex lock event on the same mutex as
158 * ordered. This is how DRD always behaves, so this macro has been defined
159 * such that it has no effect.
160 */
161 #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mtx) do { } while(0)
162
163 /** Deprecated -- don't use this annotation. */
164 #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mtx) do { } while(0)
165
166 /**
167 * Tell DRD to handle the specified memory range like a pure happens-before
168 * detector would do. Since this is how DRD always behaves, this annotation
169 * has been defined such that it has no effect.
170 */
171 #define ANNOTATE_PUBLISH_MEMORY_RANGE(addr, size) do { } while(0)
172
173 /** Deprecated -- don't use this annotation. */
174 #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(addr, size) do { } while(0)
175
176 /** Deprecated -- don't use this annotation. */
177 #define ANNOTATE_SWAP_MEMORY_RANGE(addr, size) do { } while(0)
178
179 /** Tell DRD that a reader-writer lock object has been initialized. */
180 #define ANNOTATE_RWLOCK_CREATE(rwlock) \
181 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, \
182 VG_USERREQ__DRD_ANNOTATE_RWLOCK_CREATE, \
183 rwlock, 0, 0, 0, 0);
184
185 /** Tell DRD that a reader-writer lock object has been destroyed. */
186 #define ANNOTATE_RWLOCK_DESTROY(rwlock) \
187 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, \
188 VG_USERREQ__DRD_ANNOTATE_RWLOCK_DESTROY, \
189 rwlock, 0, 0, 0, 0);
190
191 /**
192 * Tell DRD that a reader-writer lock has been acquired. is_w == 1 means that
193 * a write lock has been obtained, is_w == 0 means that a read lock has been
194 * obtained.
195 */
196 #define ANNOTATE_RWLOCK_ACQUIRED(rwlock, is_w) \
197 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, \
198 VG_USERREQ__DRD_ANNOTATE_RWLOCK_ACQUIRED, \
199 rwlock, is_w, 0, 0, 0)
200
201 /**
202 * Tell DRD that a reader lock has been acquired on a reader-writer
203 * synchronization object.
204 */
205 #define ANNOTATE_READERLOCK_ACQUIRED(rwlock) ANNOTATE_RWLOCK_ACQUIRED(rwlock, 0)
206
207 /**
208 * Tell DRD that a writer lock has been acquired on a reader-writer
209 * synchronization object.
210 */
211 #define ANNOTATE_WRITERLOCK_ACQUIRED(rwlock) ANNOTATE_RWLOCK_ACQUIRED(rwlock, 1)
212
213 /**
214 * Tell DRD that a reader-writer lock is about to be released. is_w == 1 means
215 * that a write lock is about to be released, is_w == 0 means that a read lock
216 * is about to be released.
217 */
218 #define ANNOTATE_RWLOCK_RELEASED(rwlock, is_w) \
219 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, \
220 VG_USERREQ__DRD_ANNOTATE_RWLOCK_RELEASED, \
221 rwlock, is_w, 0, 0, 0);
222
223 /**
224 * Tell DRD that a reader lock is about to be released.
225 */
226 #define ANNOTATE_READERLOCK_RELEASED(rwlock) ANNOTATE_RWLOCK_RELEASED(rwlock, 0)
227
228 /**
229 * Tell DRD that a writer lock is about to be released.
230 */
231 #define ANNOTATE_WRITERLOCK_RELEASED(rwlock) ANNOTATE_RWLOCK_RELEASED(rwlock, 1)
232
233 /*
234 * Report that a barrier has been initialized with a given barrier count. The
235 * third argument specifies whether or not reinitialization is allowed, that
236 * is, whether or not it is allowed to call barrier_init() several times
237 * without calling barrier_destroy().
238 */
239 #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \
240 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_ANNOTATION_UNIMP, \
241 "ANNOTATE_BARRIER_INIT", barrier, \
242 count, reinitialization_allowed, 0)
243
244 /* Report that a barrier has been destroyed. */
245 #define ANNOTATE_BARRIER_DESTROY(barrier) \
246 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_ANNOTATION_UNIMP, \
247 "ANNOTATE_BARRIER_DESTROY", \
248 barrier, 0, 0, 0)
249
250 /* Report that the calling thread is about to start waiting for a barrier. */
251 #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \
252 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_ANNOTATION_UNIMP, \
253 "ANNOTATE_BARRIER_WAIT_BEFORE", \
254 barrier, 0, 0, 0)
255
256 /* Report that the calling thread has just finished waiting for a barrier. */
257 #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) \
258 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_ANNOTATION_UNIMP, \
259 "ANNOTATE_BARRIER_WAIT_AFTER", \
260 barrier, 0, 0, 0)
261
262 /**
263 * Tell DRD that a FIFO queue has been created. The abbreviation PCQ stands for
264 * <em>producer-consumer</em>.
265 */
266 #define ANNOTATE_PCQ_CREATE(pcq) do { } while(0)
267
268 /** Tell DRD that a FIFO queue has been destroyed. */
269 #define ANNOTATE_PCQ_DESTROY(pcq) do { } while(0)
270
271 /**
272 * Tell DRD that an element has been added to the FIFO queue at address pcq.
273 */
274 #define ANNOTATE_PCQ_PUT(pcq) do { } while(0)
275
276 /**
277 * Tell DRD that an element has been removed from the FIFO queue at address pcq,
278 * and that DRD should insert a happens-before relationship between the memory
279 * accesses that occurred before the corresponding ANNOTATE_PCQ_PUT(pcq)
280 * annotation and the memory accesses after this annotation. Correspondence
281 * between PUT and GET annotations happens in FIFO order. Since locking
282 * of the queue is needed anyway to add elements to or to remove elements from
283 * the queue, for DRD all four FIFO annotations are defined as no-ops.
284 */
285 #define ANNOTATE_PCQ_GET(pcq) do { } while(0)
286
287 /**
288 * Tell DRD that data races at the specified address are expected and must not
289 * be reported.
290 */
291 #define ANNOTATE_BENIGN_RACE(addr, descr) \
292 ANNOTATE_BENIGN_RACE_SIZED(addr, sizeof(*addr), descr)
293
294 /* Same as ANNOTATE_BENIGN_RACE(addr, descr), but applies to
295 the memory range [addr, addr + size). */
296 #define ANNOTATE_BENIGN_RACE_SIZED(addr, size, descr) \
297 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_START_SUPPRESSION, \
298 addr, size, 0, 0, 0)
299
300 /** Tell DRD to ignore all reads performed by the current thread. */
301 #define ANNOTATE_IGNORE_READS_BEGIN() \
302 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_RECORD_LOADS, \
303 0, 0, 0, 0, 0);
304
305
306 /** Tell DRD to no longer ignore the reads performed by the current thread. */
307 #define ANNOTATE_IGNORE_READS_END() \
308 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_RECORD_LOADS, \
309 1, 0, 0, 0, 0);
310
311 /** Tell DRD to ignore all writes performed by the current thread. */
312 #define ANNOTATE_IGNORE_WRITES_BEGIN() \
313 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_RECORD_STORES, \
314 0, 0, 0, 0, 0)
315
316 /** Tell DRD to no longer ignore the writes performed by the current thread. */
317 #define ANNOTATE_IGNORE_WRITES_END() \
318 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_RECORD_STORES, \
319 1, 0, 0, 0, 0)
320
321 /** Tell DRD to ignore all memory accesses performed by the current thread. */
322 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
323 do { ANNOTATE_IGNORE_READS_BEGIN(); ANNOTATE_IGNORE_WRITES_BEGIN(); } while(0)
324
325 /**
326 * Tell DRD to no longer ignore the memory accesses performed by the current
327 * thread.
328 */
329 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \
330 do { ANNOTATE_IGNORE_READS_END(); ANNOTATE_IGNORE_WRITES_END(); } while(0)
331
332 /**
333 * Tell DRD that size bytes starting at addr has been allocated by a custom
334 * memory allocator.
335 */
336 #define ANNOTATE_NEW_MEMORY(addr, size) \
337 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_CLEAN_MEMORY, \
338 addr, size, 0, 0, 0)
339
340 /** Ask DRD to report every access to the specified address. */
341 #define ANNOTATE_TRACE_MEMORY(addr) DRD_TRACE_VAR(*(char*)(addr))
342
343 /**
344 * Tell DRD to assign the specified name to the current thread. This name will
345 * be used in error messages printed by DRD.
346 */
347 #define ANNOTATE_THREAD_NAME(name) \
348 VALGRIND_DO_CLIENT_REQUEST_EXPR(0, VG_USERREQ__DRD_SET_THREAD_NAME, \
349 name, 0, 0, 0, 0)
350
351 /*@}*/
352
353
354 /* !! ABIWARNING !! ABIWARNING !! ABIWARNING !! ABIWARNING !!
355 This enum comprises an ABI exported by Valgrind to programs
356 which use client requests. DO NOT CHANGE THE ORDER OF THESE
357 ENTRIES, NOR DELETE ANY -- add new ones at the end.
358 */
359 enum {
360 /* Ask the DRD tool to discard all information about memory accesses */
361 /* and client objects for the specified range. This client request is */
362 /* binary compatible with the similarly named Helgrind client request. */
363 VG_USERREQ__DRD_CLEAN_MEMORY = VG_USERREQ_TOOL_BASE('H','G'),
364 /* args: Addr, SizeT. */
365
366 /* Ask the DRD tool the thread ID assigned by Valgrind. */
367 VG_USERREQ__DRD_GET_VALGRIND_THREAD_ID = VG_USERREQ_TOOL_BASE('D','R'),
368 /* args: none. */
369 /* Ask the DRD tool the thread ID assigned by DRD. */
370 VG_USERREQ__DRD_GET_DRD_THREAD_ID,
371 /* args: none. */
372
373 /* To tell the DRD tool to suppress data race detection on the */
374 /* specified address range. */
375 VG_USERREQ__DRD_START_SUPPRESSION,
376 /* args: start address, size in bytes */
377 /* To tell the DRD tool no longer to suppress data race detection on */
378 /* the specified address range. */
379 VG_USERREQ__DRD_FINISH_SUPPRESSION,
380 /* args: start address, size in bytes */
381
382 /* To ask the DRD tool to trace all accesses to the specified range. */
383 VG_USERREQ__DRD_START_TRACE_ADDR,
384 /* args: Addr, SizeT. */
385 /* To ask the DRD tool to stop tracing accesses to the specified range. */
386 VG_USERREQ__DRD_STOP_TRACE_ADDR,
387 /* args: Addr, SizeT. */
388
389 /* Tell DRD whether or not to record memory loads in the calling thread. */
390 VG_USERREQ__DRD_RECORD_LOADS,
391 /* args: Bool. */
392 /* Tell DRD whether or not to record memory stores in the calling thread. */
393 VG_USERREQ__DRD_RECORD_STORES,
394 /* args: Bool. */
395
396 /* Set the name of the thread that performs this client request. */
397 VG_USERREQ__DRD_SET_THREAD_NAME,
398 /* args: null-terminated character string. */
399
400 /* Tell DRD that a DRD annotation has not yet been implemented. */
401 VG_USERREQ__DRD_ANNOTATION_UNIMP,
402 /* args: Char*. */
403
404 /* Tell DRD that a user-defined reader-writer synchronization object
405 * has been created. */
406 VG_USERREQ__DRD_ANNOTATE_RWLOCK_CREATE
407 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 14,
408 /* args: Addr. */
409 /* Tell DRD that a user-defined reader-writer synchronization object
410 * is about to be destroyed. */
411 VG_USERREQ__DRD_ANNOTATE_RWLOCK_DESTROY
412 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 15,
413 /* args: Addr. */
414 /* Tell DRD that a lock on a user-defined reader-writer synchronization
415 * object has been acquired. */
416 VG_USERREQ__DRD_ANNOTATE_RWLOCK_ACQUIRED
417 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 17,
418 /* args: Addr, Int is_rw. */
419 /* Tell DRD that a lock on a user-defined reader-writer synchronization
420 * object is about to be released. */
421 VG_USERREQ__DRD_ANNOTATE_RWLOCK_RELEASED
422 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 18,
423 /* args: Addr, Int is_rw. */
424
425 /* Tell DRD that a Helgrind annotation has not yet been implemented. */
426 VG_USERREQ__HELGRIND_ANNOTATION_UNIMP
427 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 32,
428 /* args: Char*. */
429
430 /* Tell DRD to insert a happens-before annotation. */
431 VG_USERREQ__DRD_ANNOTATE_HAPPENS_BEFORE
432 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 33,
433 /* args: Addr. */
434 /* Tell DRD to insert a happens-after annotation. */
435 VG_USERREQ__DRD_ANNOTATE_HAPPENS_AFTER
436 = VG_USERREQ_TOOL_BASE('H','G') + 256 + 34,
437 /* args: Addr. */
438
439 };
440
441
442 /**
443 * @addtogroup RaceDetectionAnnotations
444 */
445 /*@{*/
446
447 #ifdef __cplusplus
448 /* ANNOTATE_UNPROTECTED_READ is the preferred way to annotate racy reads.
449
450 Instead of doing
451 ANNOTATE_IGNORE_READS_BEGIN();
452 ... = x;
453 ANNOTATE_IGNORE_READS_END();
454 one can use
455 ... = ANNOTATE_UNPROTECTED_READ(x); */
456 template <typename T>
ANNOTATE_UNPROTECTED_READ(const volatile T & x)457 inline T ANNOTATE_UNPROTECTED_READ(const volatile T& x) {
458 ANNOTATE_IGNORE_READS_BEGIN();
459 const T result = x;
460 ANNOTATE_IGNORE_READS_END();
461 return result;
462 }
463 /* Apply ANNOTATE_BENIGN_RACE_SIZED to a static variable. */
464 #define ANNOTATE_BENIGN_RACE_STATIC(static_var, description) \
465 namespace { \
466 static class static_var##_annotator \
467 { \
468 public: \
469 static_var##_annotator() \
470 { \
471 ANNOTATE_BENIGN_RACE_SIZED(&static_var, sizeof(static_var), \
472 #static_var ": " description); \
473 } \
474 } the_##static_var##_annotator; \
475 }
476 #endif
477
478 /*@}*/
479
480 #endif /* __VALGRIND_DRD_H */
481