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