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-2013 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*, long isInit */ 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*, long isInit */ 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 _VG_USERREQ__HG_PTHREAD_COND_INIT_POST, /* pth_cond_t*, pth_cond_attr_t*/ 120 _VG_USERREQ__HG_GNAT_MASTER_HOOK, /* void*d,void*m,Word ml */ 121 _VG_USERREQ__HG_GNAT_MASTER_COMPLETED_HOOK,/* void*s,Word ml */ 122 _VG_USERREQ__HG_GET_ABITS /* Addr a,Addr abits, ulong len */ 123 } Vg_TCheckClientRequest; 124 125 126 /*----------------------------------------------------------------*/ 127 /*--- ---*/ 128 /*--- Implementation-only facilities. Not for end-user use. ---*/ 129 /*--- For end-user facilities see below (the next section in ---*/ 130 /*--- this file.) ---*/ 131 /*--- ---*/ 132 /*----------------------------------------------------------------*/ 133 134 /* Do a client request. These are macros rather than a functions so 135 as to avoid having an extra frame in stack traces. 136 137 NB: these duplicate definitions in hg_intercepts.c. But here, we 138 have to make do with weaker typing (no definition of Word etc) and 139 no assertions, whereas in helgrind.h we can use those facilities. 140 Obviously it's important the two sets of definitions are kept in 141 sync. 142 143 The commented-out asserts should actually hold, but unfortunately 144 they can't be allowed to be visible here, because that would 145 require the end-user code to #include <assert.h>. 146 */ 147 148 #define DO_CREQ_v_W(_creqF, _ty1F,_arg1F) \ 149 do { \ 150 long int _arg1; \ 151 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 152 _arg1 = (long int)(_arg1F); \ 153 VALGRIND_DO_CLIENT_REQUEST_STMT( \ 154 (_creqF), \ 155 _arg1, 0,0,0,0); \ 156 } while (0) 157 158 #define DO_CREQ_W_W(_resF, _dfltF, _creqF, _ty1F,_arg1F) \ 159 do { \ 160 long int _arg1; \ 161 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 162 _arg1 = (long int)(_arg1F); \ 163 _qzz_res = VALGRIND_DO_CLIENT_REQUEST_EXPR( \ 164 (_dfltF), \ 165 (_creqF), \ 166 _arg1, 0,0,0,0); \ 167 _resF = _qzz_res; \ 168 } while (0) 169 170 #define DO_CREQ_v_WW(_creqF, _ty1F,_arg1F, _ty2F,_arg2F) \ 171 do { \ 172 long int _arg1, _arg2; \ 173 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 174 /* assert(sizeof(_ty2F) == sizeof(long int)); */ \ 175 _arg1 = (long int)(_arg1F); \ 176 _arg2 = (long int)(_arg2F); \ 177 VALGRIND_DO_CLIENT_REQUEST_STMT( \ 178 (_creqF), \ 179 _arg1,_arg2,0,0,0); \ 180 } while (0) 181 182 #define DO_CREQ_v_WWW(_creqF, _ty1F,_arg1F, \ 183 _ty2F,_arg2F, _ty3F, _arg3F) \ 184 do { \ 185 long int _arg1, _arg2, _arg3; \ 186 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 187 /* assert(sizeof(_ty2F) == sizeof(long int)); */ \ 188 /* assert(sizeof(_ty3F) == sizeof(long int)); */ \ 189 _arg1 = (long int)(_arg1F); \ 190 _arg2 = (long int)(_arg2F); \ 191 _arg3 = (long int)(_arg3F); \ 192 VALGRIND_DO_CLIENT_REQUEST_STMT( \ 193 (_creqF), \ 194 _arg1,_arg2,_arg3,0,0); \ 195 } while (0) 196 197 #define DO_CREQ_W_WWW(_resF, _dfltF, _creqF, _ty1F,_arg1F, \ 198 _ty2F,_arg2F, _ty3F, _arg3F) \ 199 do { \ 200 long int _qzz_res; \ 201 long int _arg1, _arg2, _arg3; \ 202 /* assert(sizeof(_ty1F) == sizeof(long int)); */ \ 203 _arg1 = (long int)(_arg1F); \ 204 _arg2 = (long int)(_arg2F); \ 205 _arg3 = (long int)(_arg3F); \ 206 _qzz_res = VALGRIND_DO_CLIENT_REQUEST_EXPR( \ 207 (_dfltF), \ 208 (_creqF), \ 209 _arg1,_arg2,_arg3,0,0); \ 210 _resF = _qzz_res; \ 211 } while (0) 212 213 214 215 #define _HG_CLIENTREQ_UNIMP(_qzz_str) \ 216 DO_CREQ_v_W(_VG_USERREQ__HG_CLIENTREQ_UNIMP, \ 217 (char*),(_qzz_str)) 218 219 220 /*----------------------------------------------------------------*/ 221 /*--- ---*/ 222 /*--- Helgrind-native requests. These allow access to ---*/ 223 /*--- the same set of annotation primitives that are used ---*/ 224 /*--- to build the POSIX pthread wrappers. ---*/ 225 /*--- ---*/ 226 /*----------------------------------------------------------------*/ 227 228 /* ---------------------------------------------------------- 229 For describing ordinary mutexes (non-rwlocks). For rwlock 230 descriptions see ANNOTATE_RWLOCK_* below. 231 ---------------------------------------------------------- */ 232 233 /* Notify here immediately after mutex creation. _mbRec == 0 for a 234 non-recursive mutex, 1 for a recursive mutex. */ 235 #define VALGRIND_HG_MUTEX_INIT_POST(_mutex, _mbRec) \ 236 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_MUTEX_INIT_POST, \ 237 void*,(_mutex), long,(_mbRec)) 238 239 /* Notify here immediately before mutex acquisition. _isTryLock == 0 240 for a normal acquisition, 1 for a "try" style acquisition. */ 241 #define VALGRIND_HG_MUTEX_LOCK_PRE(_mutex, _isTryLock) \ 242 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_MUTEX_LOCK_PRE, \ 243 void*,(_mutex), long,(_isTryLock)) 244 245 /* Notify here immediately after a successful mutex acquisition. */ 246 #define VALGRIND_HG_MUTEX_LOCK_POST(_mutex) \ 247 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_LOCK_POST, \ 248 void*,(_mutex)) 249 250 /* Notify here immediately before a mutex release. */ 251 #define VALGRIND_HG_MUTEX_UNLOCK_PRE(_mutex) \ 252 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_UNLOCK_PRE, \ 253 void*,(_mutex)) 254 255 /* Notify here immediately after a mutex release. */ 256 #define VALGRIND_HG_MUTEX_UNLOCK_POST(_mutex) \ 257 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_UNLOCK_POST, \ 258 void*,(_mutex)) 259 260 /* Notify here immediately before mutex destruction. */ 261 #define VALGRIND_HG_MUTEX_DESTROY_PRE(_mutex) \ 262 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_MUTEX_DESTROY_PRE, \ 263 void*,(_mutex)) 264 265 /* ---------------------------------------------------------- 266 For describing semaphores. 267 ---------------------------------------------------------- */ 268 269 /* Notify here immediately after semaphore creation. */ 270 #define VALGRIND_HG_SEM_INIT_POST(_sem, _value) \ 271 DO_CREQ_v_WW(_VG_USERREQ__HG_POSIX_SEM_INIT_POST, \ 272 void*, (_sem), unsigned long, (_value)) 273 274 /* Notify here immediately after a semaphore wait (an acquire-style 275 operation) */ 276 #define VALGRIND_HG_SEM_WAIT_POST(_sem) \ 277 DO_CREQ_v_W(_VG_USERREQ__HG_POSIX_SEM_WAIT_POST, \ 278 void*,(_sem)) 279 280 /* Notify here immediately before semaphore post (a release-style 281 operation) */ 282 #define VALGRIND_HG_SEM_POST_PRE(_sem) \ 283 DO_CREQ_v_W(_VG_USERREQ__HG_POSIX_SEM_POST_PRE, \ 284 void*,(_sem)) 285 286 /* Notify here immediately before semaphore destruction. */ 287 #define VALGRIND_HG_SEM_DESTROY_PRE(_sem) \ 288 DO_CREQ_v_W(_VG_USERREQ__HG_POSIX_SEM_DESTROY_PRE, \ 289 void*, (_sem)) 290 291 /* ---------------------------------------------------------- 292 For describing barriers. 293 ---------------------------------------------------------- */ 294 295 /* Notify here immediately before barrier creation. _count is the 296 capacity. _resizable == 0 means the barrier may not be resized, 1 297 means it may be. */ 298 #define VALGRIND_HG_BARRIER_INIT_PRE(_bar, _count, _resizable) \ 299 DO_CREQ_v_WWW(_VG_USERREQ__HG_PTHREAD_BARRIER_INIT_PRE, \ 300 void*,(_bar), \ 301 unsigned long,(_count), \ 302 unsigned long,(_resizable)) 303 304 /* Notify here immediately before arrival at a barrier. */ 305 #define VALGRIND_HG_BARRIER_WAIT_PRE(_bar) \ 306 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_BARRIER_WAIT_PRE, \ 307 void*,(_bar)) 308 309 /* Notify here immediately before a resize (change of barrier 310 capacity). If _newcount >= the existing capacity, then there is no 311 change in the state of any threads waiting at the barrier. If 312 _newcount < the existing capacity, and >= _newcount threads are 313 currently waiting at the barrier, then this notification is 314 considered to also have the effect of telling the checker that all 315 waiting threads have now moved past the barrier. (I can't think of 316 any other sane semantics.) */ 317 #define VALGRIND_HG_BARRIER_RESIZE_PRE(_bar, _newcount) \ 318 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_BARRIER_RESIZE_PRE, \ 319 void*,(_bar), \ 320 unsigned long,(_newcount)) 321 322 /* Notify here immediately before barrier destruction. */ 323 #define VALGRIND_HG_BARRIER_DESTROY_PRE(_bar) \ 324 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_BARRIER_DESTROY_PRE, \ 325 void*,(_bar)) 326 327 /* ---------------------------------------------------------- 328 For describing memory ownership changes. 329 ---------------------------------------------------------- */ 330 331 /* Clean memory state. This makes Helgrind forget everything it knew 332 about the specified memory range. Effectively this announces that 333 the specified memory range now "belongs" to the calling thread, so 334 that: (1) the calling thread can access it safely without 335 synchronisation, and (2) all other threads must sync with this one 336 to access it safely. This is particularly useful for memory 337 allocators that wish to recycle memory. */ 338 #define VALGRIND_HG_CLEAN_MEMORY(_qzz_start, _qzz_len) \ 339 DO_CREQ_v_WW(VG_USERREQ__HG_CLEAN_MEMORY, \ 340 void*,(_qzz_start), \ 341 unsigned long,(_qzz_len)) 342 343 /* The same, but for the heap block starting at _qzz_blockstart. This 344 allows painting when we only know the address of an object, but not 345 its size, which is sometimes the case in C++ code involving 346 inheritance, and in which RTTI is not, for whatever reason, 347 available. Returns the number of bytes painted, which can be zero 348 for a zero-sized block. Hence, return values >= 0 indicate success 349 (the block was found), and the value -1 indicates block not 350 found, and -2 is returned when not running on Helgrind. */ 351 #define VALGRIND_HG_CLEAN_MEMORY_HEAPBLOCK(_qzz_blockstart) \ 352 (__extension__ \ 353 ({long int _npainted; \ 354 DO_CREQ_W_W(_npainted, (-2)/*default*/, \ 355 _VG_USERREQ__HG_CLEAN_MEMORY_HEAPBLOCK, \ 356 void*,(_qzz_blockstart)); \ 357 _npainted; \ 358 })) 359 360 /* ---------------------------------------------------------- 361 For error control. 362 ---------------------------------------------------------- */ 363 364 /* Tell H that an address range is not to be "tracked" until further 365 notice. This puts it in the NOACCESS state, in which case we 366 ignore all reads and writes to it. Useful for ignoring ranges of 367 memory where there might be races we don't want to see. If the 368 memory is subsequently reallocated via malloc/new/stack allocation, 369 then it is put back in the trackable state. Hence it is safe in 370 the situation where checking is disabled, the containing area is 371 deallocated and later reallocated for some other purpose. */ 372 #define VALGRIND_HG_DISABLE_CHECKING(_qzz_start, _qzz_len) \ 373 DO_CREQ_v_WW(_VG_USERREQ__HG_ARANGE_MAKE_UNTRACKED, \ 374 void*,(_qzz_start), \ 375 unsigned long,(_qzz_len)) 376 377 /* And put it back into the normal "tracked" state, that is, make it 378 once again subject to the normal race-checking machinery. This 379 puts it in the same state as new memory allocated by this thread -- 380 that is, basically owned exclusively by this thread. */ 381 #define VALGRIND_HG_ENABLE_CHECKING(_qzz_start, _qzz_len) \ 382 DO_CREQ_v_WW(_VG_USERREQ__HG_ARANGE_MAKE_TRACKED, \ 383 void*,(_qzz_start), \ 384 unsigned long,(_qzz_len)) 385 386 387 #define VALGRIND_HG_ENABLE_CHECKING(_qzz_start, _qzz_len) \ 388 DO_CREQ_v_WW(_VG_USERREQ__HG_ARANGE_MAKE_TRACKED, \ 389 void*,(_qzz_start), \ 390 unsigned long,(_qzz_len)) 391 392 393 /* Checks the accessibility bits for addresses [zza..zza+zznbytes-1]. 394 If zzabits array is provided, copy the accessibility bits in zzabits. 395 Return values: 396 -2 if not running on helgrind 397 -1 if any parts of zzabits is not addressable 398 >= 0 : success. 399 When success, it returns the nr of addressable bytes found. 400 So, to check that a whole range is addressable, check 401 VALGRIND_HG_GET_ABITS(addr,NULL,len) == len 402 In addition, if you want to examine the addressability of each 403 byte of the range, you need to provide a non NULL ptr as 404 second argument, pointing to an array of unsigned char 405 of length len. 406 Addressable bytes are indicated with 0xff. 407 Non-addressable bytes are indicated with 0x00. 408 */ 409 #define VALGRIND_HG_GET_ABITS(zza,zzabits,zznbytes) \ 410 (__extension__ \ 411 ({long int _res; \ 412 DO_CREQ_W_WWW(_res, (-2)/*default*/, \ 413 _VG_USERREQ__HG_GET_ABITS, \ 414 void*,(zza), void*,(zzabits), \ 415 unsigned long,(zznbytes)); \ 416 _res; \ 417 })) 418 419 /*----------------------------------------------------------------*/ 420 /*--- ---*/ 421 /*--- ThreadSanitizer-compatible requests ---*/ 422 /*--- (mostly unimplemented) ---*/ 423 /*--- ---*/ 424 /*----------------------------------------------------------------*/ 425 426 /* A quite-broad set of annotations, as used in the ThreadSanitizer 427 project. This implementation aims to be a (source-level) 428 compatible implementation of the macros defined in: 429 430 http://code.google.com/p/data-race-test/source 431 /browse/trunk/dynamic_annotations/dynamic_annotations.h 432 433 (some of the comments below are taken from the above file) 434 435 The implementation here is very incomplete, and intended as a 436 starting point. Many of the macros are unimplemented. Rather than 437 allowing unimplemented macros to silently do nothing, they cause an 438 assertion. Intention is to implement them on demand. 439 440 The major use of these macros is to make visible to race detectors, 441 the behaviour (effects) of user-implemented synchronisation 442 primitives, that the detectors could not otherwise deduce from the 443 normal observation of pthread etc calls. 444 445 Some of the macros are no-ops in Helgrind. That's because Helgrind 446 is a pure happens-before detector, whereas ThreadSanitizer uses a 447 hybrid lockset and happens-before scheme, which requires more 448 accurate annotations for correct operation. 449 450 The macros are listed in the same order as in dynamic_annotations.h 451 (URL just above). 452 453 I should point out that I am less than clear about the intended 454 semantics of quite a number of them. Comments and clarifications 455 welcomed! 456 */ 457 458 /* ---------------------------------------------------------------- 459 These four allow description of user-level condition variables, 460 apparently in the style of POSIX's pthread_cond_t. Currently 461 unimplemented and will assert. 462 ---------------------------------------------------------------- 463 */ 464 /* Report that wait on the condition variable at address CV has 465 succeeded and the lock at address LOCK is now held. CV and LOCK 466 are completely arbitrary memory addresses which presumably mean 467 something to the application, but are meaningless to Helgrind. */ 468 #define ANNOTATE_CONDVAR_LOCK_WAIT(cv, lock) \ 469 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_LOCK_WAIT") 470 471 /* Report that wait on the condition variable at CV has succeeded. 472 Variant w/o lock. */ 473 #define ANNOTATE_CONDVAR_WAIT(cv) \ 474 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_WAIT") 475 476 /* Report that we are about to signal on the condition variable at 477 address CV. */ 478 #define ANNOTATE_CONDVAR_SIGNAL(cv) \ 479 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_SIGNAL") 480 481 /* Report that we are about to signal_all on the condition variable at 482 CV. */ 483 #define ANNOTATE_CONDVAR_SIGNAL_ALL(cv) \ 484 _HG_CLIENTREQ_UNIMP("ANNOTATE_CONDVAR_SIGNAL_ALL") 485 486 487 /* ---------------------------------------------------------------- 488 Create completely arbitrary happens-before edges between threads. 489 490 If threads T1 .. Tn all do ANNOTATE_HAPPENS_BEFORE(obj) and later 491 (w.r.t. some notional global clock for the computation) thread Tm 492 does ANNOTATE_HAPPENS_AFTER(obj), then Helgrind will regard all 493 memory accesses done by T1 .. Tn before the ..BEFORE.. call as 494 happening-before all memory accesses done by Tm after the 495 ..AFTER.. call. Hence Helgrind won't complain about races if Tm's 496 accesses afterwards are to the same locations as accesses before by 497 any of T1 .. Tn. 498 499 OBJ is a machine word (unsigned long, or void*), is completely 500 arbitrary, and denotes the identity of some synchronisation object 501 you're modelling. 502 503 You must do the _BEFORE call just before the real sync event on the 504 signaller's side, and _AFTER just after the real sync event on the 505 waiter's side. 506 507 If none of the rest of these macros make sense to you, at least 508 take the time to understand these two. They form the very essence 509 of describing arbitrary inter-thread synchronisation events to 510 Helgrind. You can get a long way just with them alone. 511 512 See also, extensive discussion on semantics of this in 513 https://bugs.kde.org/show_bug.cgi?id=243935 514 515 ANNOTATE_HAPPENS_BEFORE_FORGET_ALL(obj) is interim until such time 516 as bug 243935 is fully resolved. It instructs Helgrind to forget 517 about any ANNOTATE_HAPPENS_BEFORE calls on the specified object, in 518 effect putting it back in its original state. Once in that state, 519 a use of ANNOTATE_HAPPENS_AFTER on it has no effect on the calling 520 thread. 521 522 An implementation may optionally release resources it has 523 associated with 'obj' when ANNOTATE_HAPPENS_BEFORE_FORGET_ALL(obj) 524 happens. Users are recommended to use 525 ANNOTATE_HAPPENS_BEFORE_FORGET_ALL to indicate when a 526 synchronisation object is no longer needed, so as to avoid 527 potential indefinite resource leaks. 528 ---------------------------------------------------------------- 529 */ 530 #define ANNOTATE_HAPPENS_BEFORE(obj) \ 531 DO_CREQ_v_W(_VG_USERREQ__HG_USERSO_SEND_PRE, void*,(obj)) 532 533 #define ANNOTATE_HAPPENS_AFTER(obj) \ 534 DO_CREQ_v_W(_VG_USERREQ__HG_USERSO_RECV_POST, void*,(obj)) 535 536 #define ANNOTATE_HAPPENS_BEFORE_FORGET_ALL(obj) \ 537 DO_CREQ_v_W(_VG_USERREQ__HG_USERSO_FORGET_ALL, void*,(obj)) 538 539 /* ---------------------------------------------------------------- 540 Memory publishing. The TSan sources say: 541 542 Report that the bytes in the range [pointer, pointer+size) are about 543 to be published safely. The race checker will create a happens-before 544 arc from the call ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) to 545 subsequent accesses to this memory. 546 547 I'm not sure I understand what this means exactly, nor whether it 548 is relevant for a pure h-b detector. Leaving unimplemented for 549 now. 550 ---------------------------------------------------------------- 551 */ 552 #define ANNOTATE_PUBLISH_MEMORY_RANGE(pointer, size) \ 553 _HG_CLIENTREQ_UNIMP("ANNOTATE_PUBLISH_MEMORY_RANGE") 554 555 /* DEPRECATED. Don't use it. */ 556 /* #define ANNOTATE_UNPUBLISH_MEMORY_RANGE(pointer, size) */ 557 558 /* DEPRECATED. Don't use it. */ 559 /* #define ANNOTATE_SWAP_MEMORY_RANGE(pointer, size) */ 560 561 562 /* ---------------------------------------------------------------- 563 TSan sources say: 564 565 Instruct the tool to create a happens-before arc between 566 MU->Unlock() and MU->Lock(). This annotation may slow down the 567 race detector; normally it is used only when it would be 568 difficult to annotate each of the mutex's critical sections 569 individually using the annotations above. 570 571 If MU is a posix pthread_mutex_t then Helgrind will do this anyway. 572 In any case, leave as unimp for now. I'm unsure about the intended 573 behaviour. 574 ---------------------------------------------------------------- 575 */ 576 #define ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX(mu) \ 577 _HG_CLIENTREQ_UNIMP("ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX") 578 579 /* Deprecated. Use ANNOTATE_PURE_HAPPENS_BEFORE_MUTEX. */ 580 /* #define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mu) */ 581 582 583 /* ---------------------------------------------------------------- 584 TSan sources say: 585 586 Annotations useful when defining memory allocators, or when 587 memory that was protected in one way starts to be protected in 588 another. 589 590 Report that a new memory at "address" of size "size" has been 591 allocated. This might be used when the memory has been retrieved 592 from a free list and is about to be reused, or when a the locking 593 discipline for a variable changes. 594 595 AFAICS this is the same as VALGRIND_HG_CLEAN_MEMORY. 596 ---------------------------------------------------------------- 597 */ 598 #define ANNOTATE_NEW_MEMORY(address, size) \ 599 VALGRIND_HG_CLEAN_MEMORY((address), (size)) 600 601 602 /* ---------------------------------------------------------------- 603 TSan sources say: 604 605 Annotations useful when defining FIFO queues that transfer data 606 between threads. 607 608 All unimplemented. Am not claiming to understand this (yet). 609 ---------------------------------------------------------------- 610 */ 611 612 /* Report that the producer-consumer queue object at address PCQ has 613 been created. The ANNOTATE_PCQ_* annotations should be used only 614 for FIFO queues. For non-FIFO queues use ANNOTATE_HAPPENS_BEFORE 615 (for put) and ANNOTATE_HAPPENS_AFTER (for get). */ 616 #define ANNOTATE_PCQ_CREATE(pcq) \ 617 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_CREATE") 618 619 /* Report that the queue at address PCQ is about to be destroyed. */ 620 #define ANNOTATE_PCQ_DESTROY(pcq) \ 621 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_DESTROY") 622 623 /* Report that we are about to put an element into a FIFO queue at 624 address PCQ. */ 625 #define ANNOTATE_PCQ_PUT(pcq) \ 626 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_PUT") 627 628 /* Report that we've just got an element from a FIFO queue at address 629 PCQ. */ 630 #define ANNOTATE_PCQ_GET(pcq) \ 631 _HG_CLIENTREQ_UNIMP("ANNOTATE_PCQ_GET") 632 633 634 /* ---------------------------------------------------------------- 635 Annotations that suppress errors. It is usually better to express 636 the program's synchronization using the other annotations, but 637 these can be used when all else fails. 638 639 Currently these are all unimplemented. I can't think of a simple 640 way to implement them without at least some performance overhead. 641 ---------------------------------------------------------------- 642 */ 643 644 /* Report that we may have a benign race at "pointer", with size 645 "sizeof(*(pointer))". "pointer" must be a non-void* pointer. Insert at the 646 point where "pointer" has been allocated, preferably close to the point 647 where the race happens. See also ANNOTATE_BENIGN_RACE_STATIC. 648 649 XXX: what's this actually supposed to do? And what's the type of 650 DESCRIPTION? When does the annotation stop having an effect? 651 */ 652 #define ANNOTATE_BENIGN_RACE(pointer, description) \ 653 _HG_CLIENTREQ_UNIMP("ANNOTATE_BENIGN_RACE") 654 655 /* Same as ANNOTATE_BENIGN_RACE(address, description), but applies to 656 the memory range [address, address+size). */ 657 #define ANNOTATE_BENIGN_RACE_SIZED(address, size, description) \ 658 VALGRIND_HG_DISABLE_CHECKING(address, size) 659 660 /* Request the analysis tool to ignore all reads in the current thread 661 until ANNOTATE_IGNORE_READS_END is called. Useful to ignore 662 intentional racey reads, while still checking other reads and all 663 writes. */ 664 #define ANNOTATE_IGNORE_READS_BEGIN() \ 665 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_READS_BEGIN") 666 667 /* Stop ignoring reads. */ 668 #define ANNOTATE_IGNORE_READS_END() \ 669 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_READS_END") 670 671 /* Similar to ANNOTATE_IGNORE_READS_BEGIN, but ignore writes. */ 672 #define ANNOTATE_IGNORE_WRITES_BEGIN() \ 673 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_WRITES_BEGIN") 674 675 /* Stop ignoring writes. */ 676 #define ANNOTATE_IGNORE_WRITES_END() \ 677 _HG_CLIENTREQ_UNIMP("ANNOTATE_IGNORE_WRITES_END") 678 679 /* Start ignoring all memory accesses (reads and writes). */ 680 #define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \ 681 do { \ 682 ANNOTATE_IGNORE_READS_BEGIN(); \ 683 ANNOTATE_IGNORE_WRITES_BEGIN(); \ 684 } while (0) 685 686 /* Stop ignoring all memory accesses. */ 687 #define ANNOTATE_IGNORE_READS_AND_WRITES_END() \ 688 do { \ 689 ANNOTATE_IGNORE_WRITES_END(); \ 690 ANNOTATE_IGNORE_READS_END(); \ 691 } while (0) 692 693 694 /* ---------------------------------------------------------------- 695 Annotations useful for debugging. 696 697 Again, so for unimplemented, partly for performance reasons. 698 ---------------------------------------------------------------- 699 */ 700 701 /* Request to trace every access to ADDRESS. */ 702 #define ANNOTATE_TRACE_MEMORY(address) \ 703 _HG_CLIENTREQ_UNIMP("ANNOTATE_TRACE_MEMORY") 704 705 /* Report the current thread name to a race detector. */ 706 #define ANNOTATE_THREAD_NAME(name) \ 707 _HG_CLIENTREQ_UNIMP("ANNOTATE_THREAD_NAME") 708 709 710 /* ---------------------------------------------------------------- 711 Annotations for describing behaviour of user-implemented lock 712 primitives. In all cases, the LOCK argument is a completely 713 arbitrary machine word (unsigned long, or void*) and can be any 714 value which gives a unique identity to the lock objects being 715 modelled. 716 717 We just pretend they're ordinary posix rwlocks. That'll probably 718 give some rather confusing wording in error messages, claiming that 719 the arbitrary LOCK values are pthread_rwlock_t*'s, when in fact 720 they are not. Ah well. 721 ---------------------------------------------------------------- 722 */ 723 /* Report that a lock has just been created at address LOCK. */ 724 #define ANNOTATE_RWLOCK_CREATE(lock) \ 725 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_RWLOCK_INIT_POST, \ 726 void*,(lock)) 727 728 /* Report that the lock at address LOCK is about to be destroyed. */ 729 #define ANNOTATE_RWLOCK_DESTROY(lock) \ 730 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_RWLOCK_DESTROY_PRE, \ 731 void*,(lock)) 732 733 /* Report that the lock at address LOCK has just been acquired. 734 is_w=1 for writer lock, is_w=0 for reader lock. */ 735 #define ANNOTATE_RWLOCK_ACQUIRED(lock, is_w) \ 736 DO_CREQ_v_WW(_VG_USERREQ__HG_PTHREAD_RWLOCK_LOCK_POST, \ 737 void*,(lock), unsigned long,(is_w)) 738 739 /* Report that the lock at address LOCK is about to be released. */ 740 #define ANNOTATE_RWLOCK_RELEASED(lock, is_w) \ 741 DO_CREQ_v_W(_VG_USERREQ__HG_PTHREAD_RWLOCK_UNLOCK_PRE, \ 742 void*,(lock)) /* is_w is ignored */ 743 744 745 /* ------------------------------------------------------------- 746 Annotations useful when implementing barriers. They are not 747 normally needed by modules that merely use barriers. 748 The "barrier" argument is a pointer to the barrier object. 749 ---------------------------------------------------------------- 750 */ 751 752 /* Report that the "barrier" has been initialized with initial 753 "count". If 'reinitialization_allowed' is true, initialization is 754 allowed to happen multiple times w/o calling barrier_destroy() */ 755 #define ANNOTATE_BARRIER_INIT(barrier, count, reinitialization_allowed) \ 756 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_INIT") 757 758 /* Report that we are about to enter barrier_wait("barrier"). */ 759 #define ANNOTATE_BARRIER_WAIT_BEFORE(barrier) \ 760 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_DESTROY") 761 762 /* Report that we just exited barrier_wait("barrier"). */ 763 #define ANNOTATE_BARRIER_WAIT_AFTER(barrier) \ 764 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_DESTROY") 765 766 /* Report that the "barrier" has been destroyed. */ 767 #define ANNOTATE_BARRIER_DESTROY(barrier) \ 768 _HG_CLIENTREQ_UNIMP("ANNOTATE_BARRIER_DESTROY") 769 770 771 /* ---------------------------------------------------------------- 772 Annotations useful for testing race detectors. 773 ---------------------------------------------------------------- 774 */ 775 776 /* Report that we expect a race on the variable at ADDRESS. Use only 777 in unit tests for a race detector. */ 778 #define ANNOTATE_EXPECT_RACE(address, description) \ 779 _HG_CLIENTREQ_UNIMP("ANNOTATE_EXPECT_RACE") 780 781 /* A no-op. Insert where you like to test the interceptors. */ 782 #define ANNOTATE_NO_OP(arg) \ 783 _HG_CLIENTREQ_UNIMP("ANNOTATE_NO_OP") 784 785 /* Force the race detector to flush its state. The actual effect depends on 786 * the implementation of the detector. */ 787 #define ANNOTATE_FLUSH_STATE() \ 788 _HG_CLIENTREQ_UNIMP("ANNOTATE_FLUSH_STATE") 789 790 #endif /* __HELGRIND_H */ 791