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 (at) 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> 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
