helgrind/helgrind.h

   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 */