1 /* 2 ---------------------------------------------------------------- 3 4 Notice that the above BSD-style license applies to this one file 5 (helgrind.h) only. The entire rest of Valgrind is licensed under 6 the terms of the GNU General Public License, version 2. See the 7 COPYING file in the source distribution for details. 8 9 ---------------------------------------------------------------- 10 11 This file is part of Helgrind, a Valgrind tool for detecting errors 12 in threaded programs. 13 14 Copyright (C) 2007-2011 OpenWorks LLP 15 info@open-works.co.uk 16 17 Redistribution and use in source and binary forms, with or without 18 modification, are permitted provided that the following conditions 19 are met: 20 21 1. Redistributions of source code must retain the above copyright 22 notice, this list of conditions and the following disclaimer. 23 24 2. The origin of this software must not be misrepresented; you must 25 not claim that you wrote the original software. If you use this 26 software in a product, an acknowledgment in the product 27 documentation would be appreciated but is not required. 28 29 3. Altered source versions must be plainly marked as such, and must 30 not be misrepresented as being the original software. 31 32 4. The name of the author may not be used to endorse or promote 33 products derived from this software without specific prior written 34 permission. 35 36 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 37 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 38 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 39 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 40 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 41 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 42 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 43 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 44 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 45 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 46 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 47 48 ---------------------------------------------------------------- 49 50 Notice that the above BSD-style license applies to this one file 51 (helgrind.h) only. The entire rest of Valgrind is licensed under 52 the terms of the GNU General Public License, version 2. See the 53 COPYING file in the source distribution for details. 54 55 ---------------------------------------------------------------- 56 */ 57 58 #ifndef __HELGRIND_H 59 #define __HELGRIND_H 60 61 #include "valgrind.h" 62 63 /* !! ABIWARNING !! ABIWARNING !! ABIWARNING !! ABIWARNING !! 64 This enum comprises an ABI exported by Valgrind to programs 65 which use client requests. DO NOT CHANGE THE ORDER OF THESE 66 ENTRIES, NOR DELETE ANY -- add new ones at the end. */ 67 typedef 68 enum { 69 VG_USERREQ__HG_CLEAN_MEMORY = VG_USERREQ_TOOL_BASE('H','G'), 70 71 /* The rest are for Helgrind's internal use. Not for end-user 72 use. Do not use them unless you are a Valgrind developer. */ 73 74 /* Notify the tool what this thread's pthread_t is. */ 75 _VG_USERREQ__HG_SET_MY_PTHREAD_T = VG_USERREQ_TOOL_BASE('H','G') 76 + 256, 77 _VG_USERREQ__HG_PTH_API_ERROR, /* char*, int */ 78 _VG_USERREQ__HG_PTHREAD_JOIN_POST, /* pthread_t of quitter */ 79 _VG_USERREQ__HG_PTHREAD_MUTEX_INIT_POST, /* pth_mx_t*, long mbRec */ 80 _VG_USERREQ__HG_PTHREAD_MUTEX_DESTROY_PRE, /* pth_mx_t* */ 81 _VG_USERREQ__HG_PTHREAD_MUTEX_UNLOCK_PRE, /* pth_mx_t* */ 82 _VG_USERREQ__HG_PTHREAD_MUTEX_UNLOCK_POST, /* pth_mx_t* */ 83 _VG_USERREQ__HG_PTHREAD_MUTEX_LOCK_PRE, /* pth_mx_t*, long isTryLock */ 84 _VG_USERREQ__HG_PTHREAD_MUTEX_LOCK_POST, /* pth_mx_t* */ 85 _VG_USERREQ__HG_PTHREAD_COND_SIGNAL_PRE, /* pth_cond_t* */ 86 _VG_USERREQ__HG_PTHREAD_COND_BROADCAST_PRE, /* pth_cond_t* */ 87 _VG_USERREQ__HG_PTHREAD_COND_WAIT_PRE, /* pth_cond_t*, pth_mx_t* */ 88 _VG_USERREQ__HG_PTHREAD_COND_WAIT_POST, /* pth_cond_t*, pth_mx_t* */ 89 _VG_USERREQ__HG_PTHREAD_COND_DESTROY_PRE, /* pth_cond_t* */ 90 _VG_USERREQ__HG_PTHREAD_RWLOCK_INIT_POST, /* pth_rwlk_t* */ 91 _VG_USERREQ__HG_PTHREAD_RWLOCK_DESTROY_PRE, /* pth_rwlk_t* */ 92 _VG_USERREQ__HG_PTHREAD_RWLOCK_LOCK_PRE, /* pth_rwlk_t*, long isW */ 93 _VG_USERREQ__HG_PTHREAD_RWLOCK_LOCK_POST, /* pth_rwlk_t*, long isW */ 94 _VG_USERREQ__HG_PTHREAD_RWLOCK_UNLOCK_PRE, /* pth_rwlk_t* */ 95 _VG_USERREQ__HG_PTHREAD_RWLOCK_UNLOCK_POST, /* pth_rwlk_t* */ 96 _VG_USERREQ__HG_POSIX_SEM_INIT_POST, /* sem_t*, ulong value */ 97 _VG_USERREQ__HG_POSIX_SEM_DESTROY_PRE, /* sem_t* */ 98 _VG_USERREQ__HG_POSIX_SEM_POST_PRE, /* sem_t* */ 99 _VG_USERREQ__HG_POSIX_SEM_WAIT_POST, /* sem_t* */ 100 _VG_USERREQ__HG_PTHREAD_BARRIER_INIT_PRE, /* pth_bar_t*, ulong, ulong */ 101 _VG_USERREQ__HG_PTHREAD_BARRIER_WAIT_PRE, /* pth_bar_t* */ 102 _VG_USERREQ__HG_PTHREAD_BARRIER_DESTROY_PRE, /* pth_bar_t* */ 103 _VG_USERREQ__HG_PTHREAD_SPIN_INIT_OR_UNLOCK_PRE, /* pth_slk_t* */ 104 _VG_USERREQ__HG_PTHREAD_SPIN_INIT_OR_UNLOCK_POST, /* pth_slk_t* */ 105 _VG_USERREQ__HG_PTHREAD_SPIN_LOCK_PRE, /* pth_slk_t* */ 106 _VG_USERREQ__HG_PTHREAD_SPIN_LOCK_POST, /* pth_slk_t* */ 107 _VG_USERREQ__HG_PTHREAD_SPIN_DESTROY_PRE, /* pth_slk_t* */ 108 _VG_USERREQ__HG_CLIENTREQ_UNIMP, /* char* */ 109 _VG_USERREQ__HG_USERSO_SEND_PRE, /* arbitrary UWord SO-tag */ 110 _VG_USERREQ__HG_USERSO_RECV_POST, /* arbitrary UWord SO-tag */ 111 _VG_USERREQ__HG_USERSO_FORGET_ALL, /* arbitrary UWord SO-tag */ 112 _VG_USERREQ__HG_RESERVED2, /* Do not use */ 113 _VG_USERREQ__HG_RESERVED3, /* Do not use */ 114 _VG_USERREQ__HG_RESERVED4, /* Do not use */ 115 _VG_USERREQ__HG_ARANGE_MAKE_UNTRACKED, /* Addr a, ulong len */ 116 _VG_USERREQ__HG_ARANGE_MAKE_TRACKED, /* Addr a, ulong len */ 117 _VG_USERREQ__HG_PTHREAD_BARRIER_RESIZE_PRE, /* pth_bar_t*, ulong */ 118 _VG_USERREQ__HG_CLEAN_MEMORY_HEAPBLOCK /* Addr start_of_block */ 119 120 } Vg_TCheckClientRequest; 121 122 123 /*----------------------------------------------------------------*/ 124 /*--- ---*/ 125 /*--- Implementation-only facilities. Not for end-user use. ---*/ 126 /*--- For end-user facilities see below (the next section in ---*/ 127 /*--- this file.) ---*/ 128 /*--- ---*/ 129 /*----------------------------------------------------------------*/ 130 131 /* Do a client request. These are macros rather than a functions so 132 as to avoid having an extra frame in stack traces. 133 134 NB: these duplicate definitions in hg_intercepts.c. But here, we 135 have to make do with weaker typing (no definition of Word etc) and 136 no assertions, whereas in helgrind.h we can use those facilities. 137 Obviously it's important the two sets of definitions are kept in 138 sync. 139 140 The commented-out asserts should actually hold, but unfortunately 141 they can't be allowed to be visible here, because that would 142 require the end-user code to #include <assert.h>. 143 */ 144 145 #define DO_CREQ_v_W(_creqF, _ty1F,_arg1F) \ 146 do { \ 147 long int _arg1; \ 148 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 149 _arg1 = (long int)(_arg1F); \ 150 VALGRIND_DO_CLIENT_REQUEST_STMT( \ 151 (_creqF), \ 152 _arg1, 0,0,0,0); \ 153 } while (0) 154 155 #define DO_CREQ_W_W(_resF, _dfltF, _creqF, _ty1F,_arg1F) \ 156 do { \ 157 long int arg1; \ 158 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 159 _arg1 = (long int)(_arg1F); \ 160 _qzz_res = VALGRIND_DO_CLIENT_REQUEST_EXPR( \ 161 (_dfltF), \ 162 (_creqF), \ 163 _arg1, 0,0,0,0); \ 164 _resF = _qzz_res; \ 165 } while (0) 166 167 #define DO_CREQ_v_WW(_creqF, _ty1F,_arg1F, _ty2F,_arg2F) \ 168 do { \ 169 long int _arg1, _arg2; \ 170 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 171 /* assert(sizeof(_ty2F) == sizeof(long int)); */ \ 172 _arg1 = (long int)(_arg1F); \ 173 _arg2 = (long int)(_arg2F); \ 174 VALGRIND_DO_CLIENT_REQUEST_STMT( \ 175 (_creqF), \ 176 _arg1,_arg2,0,0,0); \ 177 } while (0) 178 179 #define DO_CREQ_v_WWW(_creqF, _ty1F,_arg1F, \ 180 _ty2F,_arg2F, _ty3F, _arg3F) \ 181 do { \ 182 long int _arg1, _arg2, _arg3; \ 183 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 184 /* assert(sizeof(_ty2F) == sizeof(long int)); */ \ 185 /* assert(sizeof(_ty3F) == sizeof(long int)); */ \ 186 _arg1 = (long int)(_arg1F); \ 187 _arg2 = (long int)(_arg2F); \ 188 _arg3 = (long int)(_arg3F); \ 189 VALGRIND_DO_CLIENT_REQUEST_STMT( \ 190 (_creqF), \ 191 _arg1,_arg2,_arg3,0,0); \ 192 } while (0) 193 194 195 #define _HG_CLIENTREQ_UNIMP(_qzz_str) \ 196 DO_CREQ_v_W(_VG_USERREQ__HG_CLIENTREQ_UNIMP, \ 197 (char*),(_qzz_str)) 198 199 200 /*----------------------------------------------------------------*/ 201 /*--- ---*/ 202 /*--- Helgrind-native requests. These allow access to ---*/ 203 /*--- the same set of annotation primitives that are used ---*/ 204 /*--- to build the POSIX pthread wrappers. ---*/ 205 /*--- ---*/ 206 /*----------------------------------------------------------------*/ 207 208 /* ---------------------------------------------------------- 209 For describing ordinary mutexes (non-rwlocks). For rwlock 210 descriptions see ANNOTATE_RWLOCK_* below. 211 ---------------------------------------------------------- */ 212 213 /* Notify here immediately after mutex creation. _mbRec == 0 for a 214 non-recursive mutex, 1 for a recursive mutex. */ 215 #define VALGRIND_HG_MUTEX_INIT_POST(_mutex, _mbRec) \ 216 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_MUTEX_INIT_POST, \ 217 void*,(_mutex), long,(_mbRec)) 218 219 /* Notify here immediately before mutex acquisition. _isTryLock == 0 220 for a normal acquisition, 1 for a "try" style acquisition. */ 221 #define VALGRIND_HG_MUTEX_LOCK_PRE(_mutex, _isTryLock) \ 222 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_MUTEX_LOCK_PRE, \ 223 void*,(_mutex), long,(_isTryLock)) 224 225 /* Notify here immediately after a successful mutex acquisition. */ 226 #define VALGRIND_HG_MUTEX_LOCK_POST(_mutex) \ 227 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_LOCK_POST, \ 228 void*,(_mutex)) 229 230 /* Notify here immediately before a mutex release. */ 231 #define VALGRIND_HG_MUTEX_UNLOCK_PRE(_mutex) \ 232 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_UNLOCK_PRE, \ 233 void*,(_mutex)) 234 235 /* Notify here immediately after a mutex release. */ 236 #define VALGRIND_HG_MUTEX_UNLOCK_POST(_mutex) \ 237 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_UNLOCK_POST, \ 238 void*,(_mutex)) 239 240 /* Notify here immediately before mutex destruction. */ 241 #define VALGRIND_HG_MUTEX_DESTROY_PRE(_mutex) \ 242 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_DESTROY_PRE, \ 243 void*,(_mutex)) 244 245 /* ---------------------------------------------------------- 246 For describing semaphores. 247 ---------------------------------------------------------- */ 248 249 /* Notify here immediately after semaphore creation. */ 250 #define VALGRIND_HG_SEM_INIT_POST(_sem, _value) \ 251 DO_CREQ_v_WW(_VG_USERREQ__HG_POSIX_SEM_INIT_POST, \ 252 void*, (_sem), unsigned long, (_value)) 253 254 /* Notify here immediately after a semaphore wait (an acquire-style 255 operation) */ 256 #define VALGRIND_HG_SEM_WAIT_POST(_sem) \ 257 DO_CREQ_v_W(_VG_USERREQ__HG_POSIX_SEM_WAIT_POST, \ 258 void*,(_sem)) 259 260 /* Notify here immediately before semaphore post (a release-style 261 operation) */ 262 #define VALGRIND_HG_SEM_POST_PRE(_sem) \ 263 DO_CREQ_v_W(_VG_USERREQ__HG_POSIX_SEM_POST_PRE, \ 264 void*,(_sem)) 265 266 /* Notify here immediately before semaphore destruction. */ 267 #define VALGRIND_HG_SEM_DESTROY_PRE(_sem) \ 268 DO_CREQ_v_W(_VG_USERREQ__HG_POSIX_SEM_DESTROY_PRE, \ 269 void*, (_sem)) 270 271 /* ---------------------------------------------------------- 272 For describing barriers. 273 ---------------------------------------------------------- */ 274 275 /* Notify here immediately before barrier creation. _count is the 276 capacity. _resizable == 0 means the barrier may not be resized, 1 277 means it may be. */ 278 #define VALGRIND_HG_BARRIER_INIT_PRE(_bar, _count, _resizable) \ 279 DO_CREQ_v_WWW(_VG_USERREQ__HG_PTHREAD_BARRIER_INIT_PRE, \ 280 void*,(_bar), \ 281 unsigned long,(_count), \ 282 unsigned long,(_resizable)) 283 284 /* Notify here immediately before arrival at a barrier. */ 285 #define VALGRIND_HG_BARRIER_WAIT_PRE(_bar) \ 286 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_BARRIER_WAIT_PRE, \ 287 void*,(_bar)) 288 289 /* Notify here immediately before a resize (change of barrier 290 capacity). If _newcount >= the existing capacity, then there is no 291 change in the state of any threads waiting at the barrier. If 292 _newcount < the existing capacity, and >= _newcount threads are 293 currently waiting at the barrier, then this notification is 294 considered to also have the effect of telling the checker that all 295 waiting threads have now moved past the barrier. (I can't think of 296 any other sane semantics.) */ 297 #define VALGRIND_HG_BARRIER_RESIZE_PRE(_bar, _newcount) \ 298 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_BARRIER_RESIZE_PRE, \ 299 void*,(_bar), \ 300 unsigned long,(_newcount)) 301 302 /* Notify here immediately before barrier destruction. */ 303 #define VALGRIND_HG_BARRIER_DESTROY_PRE(_bar) \ 304 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_BARRIER_DESTROY_PRE, \ 305 void*,(_bar)) 306 307 /* ---------------------------------------------------------- 308 For describing memory ownership changes. 309 ---------------------------------------------------------- */ 310 311 /* Clean memory state. This makes Helgrind forget everything it knew 312 about the specified memory range. Effectively this announces that 313 the specified memory range now "belongs" to the calling thread, so 314 that: (1) the calling thread can access it safely without 315 synchronisation, and (2) all other threads must sync with this one 316 to access it safely. This is particularly useful for memory 317 allocators that wish to recycle memory. */ 318 #define VALGRIND_HG_CLEAN_MEMORY(_qzz_start, _qzz_len) \ 319 DO_CREQ_v_WW(VG_USERREQ__HG_CLEAN_MEMORY, \ 320 void*,(_qzz_start), \ 321 unsigned long,(_qzz_len)) 322 323 /* The same, but for the heap block starting at _qzz_blockstart. This 324 allows painting when we only know the address of an object, but not 325 its size, which is sometimes the case in C++ code involving 326 inheritance, and in which RTTI is not, for whatever reason, 327 available. Returns the number of bytes painted, which can be zero 328 for a zero-sized block. Hence, return values >= 0 indicate success 329 (the block was found), and the value -1 indicates block not 330 found, and -2 is returned when not running on Helgrind. */ 331 #define VALGRIND_HG_CLEAN_MEMORY_HEAPBLOCK(_qzz_blockstart) \ 332 (__extension__ \ 333 ({long int _npainted; \ 334 DO_CREQ_W_W(_npainted, (-2)/*default*/, \ 335 _VG_USERREQ__HG_CLEAN_MEMORY_HEAPBLOCK, \ 336 void*,(_qzz_blockstart)); \ 337 _npainted; \ 338 })) 339 340 /* ---------------------------------------------------------- 341 For error control. 342 ---------------------------------------------------------- */ 343 344 /* Tell H that an address range is not to be "tracked" until further 345 notice. This puts it in the NOACCESS state, in which case we 346 ignore all reads and writes to it. Useful for ignoring ranges of 347 memory where there might be races we don't want to see. If the 348 memory is subsequently reallocated via malloc/new/stack allocation, 349 then it is put back in the trackable state. Hence it is safe in 350 the situation where checking is disabled, the containing area is 351 deallocated and later reallocated for some other purpose. */ 352 #define VALGRIND_HG_DISABLE_CHECKING(_qzz_start, _qzz_len) \ 353 DO_CREQ_v_WW(_VG_USERREQ__HG_ARANGE_MAKE_UNTRACKED, \ 354 void*,(_qzz_start), \ 355 unsigned long,(_qzz_len)) 356 357 /* And put it back into the normal "tracked" state, that is, make it 358 once again subject to the normal race-checking machinery. This 359 puts it in the same state as new memory allocated by this thread -- 360 that is, basically owned exclusively by this thread. */ 361 #define VALGRIND_HG_ENABLE_CHECKING(_qzz_start, _qzz_len) \ 362 DO_CREQ_v_WW(_VG_USERREQ__HG_ARANGE_MAKE_TRACKED, \ 363 void*,(_qzz_start), \ 364 unsigned long,(_qzz_len)) 365 366 367 /*----------------------------------------------------------------*/ 368 /*--- ---*/ 369 /*--- ThreadSanitizer-compatible requests ---*/ 370 /*--- (mostly unimplemented) ---*/ 371 /*--- ---*/ 372 /*----------------------------------------------------------------*/ 373 374 /* A quite-broad set of annotations, as used in the ThreadSanitizer 375 project. This implementation aims to be a (source-level) 376 compatible implementation of the macros defined in: 377 378 http://code.google.com/p/data-race-test/source 379 /browse/trunk/dynamic_annotations/dynamic_annotations.h 380 381 (some of the comments below are taken from the above file) 382 383 The implementation here is very incomplete, and intended as a 384 starting point. Many of the macros are unimplemented. Rather than 385 allowing unimplemented macros to silently do nothing, they cause an 386 assertion. Intention is to implement them on demand. 387 388 The major use of these macros is to make visible to race detectors, 389 the behaviour (effects) of user-implemented synchronisation 390 primitives, that the detectors could not otherwise deduce from the 391 normal observation of pthread etc calls. 392 393 Some of the macros are no-ops in Helgrind. That's because Helgrind 394 is a pure happens-before detector, whereas ThreadSanitizer uses a 395 hybrid lockset and happens-before scheme, which requires more 396 accurate annotations for correct operation. 397 398 The macros are listed in the same order as in dynamic_annotations.h 399 (URL just above). 400 401 I should point out that I am less than clear about the intended 402 semantics of quite a number of them. Comments and clarifications 403 welcomed! 404 */ 405 406 /* ---------------------------------------------------------------- 407 These four allow description of user-level condition variables, 408 apparently in the style of POSIX's pthread_cond_t. Currently 409 unimplemented and will assert. 410 ---------------------------------------------------------------- 411 */ 412 /* Report that wait on the condition variable at address CV has 413 succeeded and the lock at address LOCK is now held. CV and LOCK 414 are completely arbitrary memory addresses which presumably mean 415 something to the application, but are meaningless to Helgrind. */ 416 #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) \ 417 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_LOCK_WAIT") 418 419 /* Report that wait on the condition variable at CV has succeeded. 420 Variant w/o lock. */ 421 #define ANNOTATE_CONDVAR_WAIT(cv) \ 422 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_WAIT") 423 424 /* Report that we are about to signal on the condition variable at 425 address CV. */ 426 #define ANNOTATE_CONDVAR_SIGNAL(cv) \ 427 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_SIGNAL") 428 429 /* Report that we are about to signal_all on the condition variable at 430 CV. */ 431 #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) \ 432 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_SIGNAL_ALL") 433 434 435 /* ---------------------------------------------------------------- 436 Create completely arbitrary happens-before edges between threads. 437 438 If threads T1 .. Tn all do ANNOTATE_HAPPENS_BEFORE(obj) and later 439 (w.r.t. some notional global clock for the computation) thread Tm 440 does ANNOTATE_HAPPENS_AFTER(obj), then Helgrind will regard all 441 memory accesses done by T1 .. Tn before the ..BEFORE.. call as 442 happening-before all memory accesses done by Tm after the 443 ..AFTER.. call. Hence Helgrind won't complain about races if Tm's 444 accesses afterwards are to the same locations as accesses before by 445 any of T1 .. Tn. 446 447 OBJ is a machine word (unsigned long, or void*), is completely 448 arbitrary, and denotes the identity of some synchronisation object 449 you're modelling. 450 451 You must do the _BEFORE call just before the real sync event on the 452 signaller's side, and _AFTER just after the real sync event on the 453 waiter's side. 454 455 If none of the rest of these macros make sense to you, at least 456 take the time to understand these two. They form the very essence 457 of describing arbitrary inter-thread synchronisation events to 458 Helgrind. You can get a long way just with them alone. 459 460 See also, extensive discussion on semantics of this in 461 https://bugs.kde.org/show_bug.cgi?id=243935 462 463 ANNOTATE_HAPPENS_BEFORE_FORGET_ALL(obj) is interim until such time 464 as bug 243935 is fully resolved. It instructs Helgrind to forget 465 about any ANNOTATE_HAPPENS_BEFORE calls on the specified object, in 466 effect putting it back in its original state. Once in that state, 467 a use of ANNOTATE_HAPPENS_AFTER on it has no effect on the calling 468 thread. 469 470 An implementation may optionally release resources it has 471 associated with 'obj' when ANNOTATE_HAPPENS_BEFORE_FORGET_ALL(obj) 472 happens. Users are recommended to use 473 ANNOTATE_HAPPENS_BEFORE_FORGET_ALL to indicate when a 474 synchronisation object is no longer needed, so as to avoid 475 potential indefinite resource leaks. 476 ---------------------------------------------------------------- 477 */ 478 #define ANNOTATE_HAPPENS_BEFORE(obj) \ 479 DO_CREQ_v_W(_VG_USERREQ__HG_USERSO_SEND_PRE, void*,(obj)) 480 481 #define ANNOTATE_HAPPENS_AFTER(obj) \ 482 DO_CREQ_v_W(_VG_USERREQ__HG_USERSO_RECV_POST, void*,(obj)) 483 484 #define ANNOTATE_HAPPENS_BEFORE_FORGET_ALL(obj) \ 485 DO_CREQ_v_W(_VG_USERREQ__HG_USERSO_FORGET_ALL, void*,(obj)) 486 487 /* ---------------------------------------------------------------- 488 Memory publishing. The TSan sources say: 489 490 Report that the bytes in the range [pointer, pointer+size) are about 491 to be published safely. The race checker will create a happens-before 492 arc from the call ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) to 493 subsequent accesses to this memory. 494 495 I'm not sure I understand what this means exactly, nor whether it 496 is relevant for a pure h-b detector. Leaving unimplemented for 497 now. 498 ---------------------------------------------------------------- 499 */ 500 #define ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) \ 501 _HG_CLIENTREQ_UNIMP("ANNOTATE_PUBLISH_MEMORY_RANGE") 502 503 /* DEPRECATED. Don't use it. */ 504 /* #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(pointer, size) */ 505 506 /* DEPRECATED. Don't use it. */ 507 /* #define ANNOTATE_SWAP_MEMORY_RANGE(pointer, size) */ 508 509 510 /* ---------------------------------------------------------------- 511 TSan sources say: 512 513 Instruct the tool to create a happens-before arc between 514 MU->Unlock() and MU->Lock(). This annotation may slow down the 515 race detector; normally it is used only when it would be 516 difficult to annotate each of the mutex's critical sections 517 individually using the annotations above. 518 519 If MU is a posix pthread_mutex_t then Helgrind will do this anyway. 520 In any case, leave as unimp for now. I'm unsure about the intended 521 behaviour. 522 ---------------------------------------------------------------- 523 */ 524 #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) \ 525 _HG_CLIENTREQ_UNIMP("ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX") 526 527 /* Deprecated. Use ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX. */ 528 /* #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) */ 529 530 531 /* ---------------------------------------------------------------- 532 TSan sources say: 533 534 Annotations useful when defining memory allocators, or when 535 memory that was protected in one way starts to be protected in 536 another. 537 538 Report that a new memory at "address" of size "size" has been 539 allocated. This might be used when the memory has been retrieved 540 from a free list and is about to be reused, or when a the locking 541 discipline for a variable changes. 542 543 AFAICS this is the same as VALGRIND_HG_CLEAN_MEMORY. 544 ---------------------------------------------------------------- 545 */ 546 #define ANNOTATE_NEW_MEMORY(address, size) \ 547 VALGRIND_HG_CLEAN_MEMORY((address), (size)) 548 549 550 /* ---------------------------------------------------------------- 551 TSan sources say: 552 553 Annotations useful when defining FIFO queues that transfer data 554 between threads. 555 556 All unimplemented. Am not claiming to understand this (yet). 557 ---------------------------------------------------------------- 558 */ 559 560 /* Report that the producer-consumer queue object at address PCQ has 561 been created. The ANNOTATE_PCQ_* annotations should be used only 562 for FIFO queues. For non-FIFO queues use ANNOTATE_HAPPENS_BEFORE 563 (for put) and ANNOTATE_HAPPENS_AFTER (for get). */ 564 #define ANNOTATE_PCQ_CREATE(pcq) \ 565 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_CREATE") 566 567 /* Report that the queue at address PCQ is about to be destroyed. */ 568 #define ANNOTATE_PCQ_DESTROY(pcq) \ 569 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_DESTROY") 570 571 /* Report that we are about to put an element into a FIFO queue at 572 address PCQ. */ 573 #define ANNOTATE_PCQ_PUT(pcq) \ 574 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_PUT") 575 576 /* Report that we've just got an element from a FIFO queue at address 577 PCQ. */ 578 #define ANNOTATE_PCQ_GET(pcq) \ 579 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_GET") 580 581 582 /* ---------------------------------------------------------------- 583 Annotations that suppress errors. It is usually better to express 584 the program's synchronization using the other annotations, but 585 these can be used when all else fails. 586 587 Currently these are all unimplemented. I can't think of a simple 588 way to implement them without at least some performance overhead. 589 ---------------------------------------------------------------- 590 */ 591 592 /* Report that we may have a benign race at "pointer", with size 593 "sizeof(*(pointer))". "pointer" must be a non-void* pointer. Insert at the 594 point where "pointer" has been allocated, preferably close to the point 595 where the race happens. See also ANNOTATE_BENIGN_RACE_STATIC. 596 597 XXX: what's this actually supposed to do? And what's the type of 598 DESCRIPTION? When does the annotation stop having an effect? 599 */ 600 #define ANNOTATE_BENIGN_RACE(pointer, description) \ 601 _HG_CLIENTREQ_UNIMP("ANNOTATE_BENIGN_RACE") 602 603 /* Same as ANNOTATE_BENIGN_RACE(address, description), but applies to 604 the memory range [address, address+size). */ 605 #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \ 606 _HG_CLIENTREQ_UNIMP("ANNOTATE_BENIGN_RACE_SIZED") 607 608 /* Request the analysis tool to ignore all reads in the current thread 609 until ANNOTATE_IGNORE_READS_END is called. Useful to ignore 610 intentional racey reads, while still checking other reads and all 611 writes. */ 612 #define ANNOTATE_IGNORE_READS_BEGIN() \ 613 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_READS_BEGIN") 614 615 /* Stop ignoring reads. */ 616 #define ANNOTATE_IGNORE_READS_END() \ 617 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_READS_END") 618 619 /* Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore writes. */ 620 #define ANNOTATE_IGNORE_WRITES_BEGIN() \ 621 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_WRITES_BEGIN") 622 623 /* Stop ignoring writes. */ 624 #define ANNOTATE_IGNORE_WRITES_END() \ 625 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_WRITES_END") 626 627 /* Start ignoring all memory accesses (reads and writes). */ 628 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \ 629 do { \ 630 ANNOTATE_IGNORE_READS_BEGIN(); \ 631 ANNOTATE_IGNORE_WRITES_BEGIN(); \ 632 } while (0) 633 634 /* Stop ignoring all memory accesses. */ 635 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \ 636 do { \ 637 ANNOTATE_IGNORE_WRITES_END(); \ 638 ANNOTATE_IGNORE_READS_END(); \ 639 } while (0) 640 641 642 /* ---------------------------------------------------------------- 643 Annotations useful for debugging. 644 645 Again, so for unimplemented, partly for performance reasons. 646 ---------------------------------------------------------------- 647 */ 648 649 /* Request to trace every access to ADDRESS. */ 650 #define ANNOTATE_TRACE_MEMORY(address) \ 651 _HG_CLIENTREQ_UNIMP("ANNOTATE_TRACE_MEMORY") 652 653 /* Report the current thread name to a race detector. */ 654 #define ANNOTATE_THREAD_NAME(name) \ 655 _HG_CLIENTREQ_UNIMP("ANNOTATE_THREAD_NAME") 656 657 658 /* ---------------------------------------------------------------- 659 Annotations for describing behaviour of user-implemented lock 660 primitives. In all cases, the LOCK argument is a completely 661 arbitrary machine word (unsigned long, or void*) and can be any 662 value which gives a unique identity to the lock objects being 663 modelled. 664 665 We just pretend they're ordinary posix rwlocks. That'll probably 666 give some rather confusing wording in error messages, claiming that 667 the arbitrary LOCK values are pthread_rwlock_t*'s, when in fact 668 they are not. Ah well. 669 ---------------------------------------------------------------- 670 */ 671 /* Report that a lock has just been created at address LOCK. */ 672 #define ANNOTATE_RWLOCK_CREATE(lock) \ 673 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_RWLOCK_INIT_POST, \ 674 void*,(lock)) 675 676 /* Report that the lock at address LOCK is about to be destroyed. */ 677 #define ANNOTATE_RWLOCK_DESTROY(lock) \ 678 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_RWLOCK_DESTROY_PRE, \ 679 void*,(lock)) 680 681 /* Report that the lock at address LOCK has just been acquired. 682 is_w=1 for writer lock, is_w=0 for reader lock. */ 683 #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \ 684 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_RWLOCK_LOCK_POST, \ 685 void*,(lock), unsigned long,(is_w)) 686 687 /* Report that the lock at address LOCK is about to be released. */ 688 #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ 689 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_RWLOCK_UNLOCK_PRE, \ 690 void*,(lock)) /* is_w is ignored */ 691 692 693 /* ------------------------------------------------------------- 694 Annotations useful when implementing barriers. They are not 695 normally needed by modules that merely use barriers. 696 The "barrier" argument is a pointer to the barrier object. 697 ---------------------------------------------------------------- 698 */ 699 700 /* Report that the "barrier" has been initialized with initial 701 "count". If 'reinitialization_allowed' is true, initialization is 702 allowed to happen multiple times w/o calling barrier_destroy() */ 703 #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \ 704 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_INIT") 705 706 /* Report that we are about to enter barrier_wait("barrier"). */ 707 #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \ 708 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_DESTROY") 709 710 /* Report that we just exited barrier_wait("barrier"). */ 711 #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) \ 712 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_DESTROY") 713 714 /* Report that the "barrier" has been destroyed. */ 715 #define ANNOTATE_BARRIER_DESTROY(barrier) \ 716 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_DESTROY") 717 718 719 /* ---------------------------------------------------------------- 720 Annotations useful for testing race detectors. 721 ---------------------------------------------------------------- 722 */ 723 724 /* Report that we expect a race on the variable at ADDRESS. Use only 725 in unit tests for a race detector. */ 726 #define ANNOTATE_EXPECT_RACE(address, description) \ 727 _HG_CLIENTREQ_UNIMP("ANNOTATE_EXPECT_RACE") 728 729 /* A no-op. Insert where you like to test the interceptors. */ 730 #define ANNOTATE_NO_OP(arg) \ 731 _HG_CLIENTREQ_UNIMP("ANNOTATE_NO_OP") 732 733 /* Force the race detector to flush its state. The actual effect depends on 734 * the implementation of the detector. */ 735 #define ANNOTATE_FLUSH_STATE() \ 736 _HG_CLIENTREQ_UNIMP("ANNOTATE_FLUSH_STATE") 737 738 #endif /* __HELGRIND_H */ 739