blob: 9669f0978ccd2f0ba974307c5f3f41c088e1a5f7 [file] [log] [blame]
bartbedfd232009-03-26 19:07:15 +00001/* -*- mode: C; c-basic-offset: 3; -*- */
bart3c1e9d82008-06-30 17:10:29 +00002
3/*
bartbedfd232009-03-26 19:07:15 +00004 ----------------------------------------------------------------
bart3c1e9d82008-06-30 17:10:29 +00005
bartbedfd232009-03-26 19:07:15 +00006 Notice that the following BSD-style license applies to this one
7 file (drd.h) only. The rest of Valgrind is licensed under the
8 terms of the GNU General Public License, version 2, unless
9 otherwise indicated. See the COPYING file in the source
10 distribution for details.
bart3c1e9d82008-06-30 17:10:29 +000011
bartbedfd232009-03-26 19:07:15 +000012 ----------------------------------------------------------------
bart3c1e9d82008-06-30 17:10:29 +000013
bartd45d9952009-05-31 18:53:54 +000014 This file is part of DRD, a Valgrind tool for verification of
bartbedfd232009-03-26 19:07:15 +000015 multithreaded programs.
bart3c1e9d82008-06-30 17:10:29 +000016
bartbedfd232009-03-26 19:07:15 +000017 Copyright (C) 2006-2009 Bart Van Assche <bart.vanassche@gmail.com>.
18 All rights reserved.
bart3c1e9d82008-06-30 17:10:29 +000019
bartbedfd232009-03-26 19:07:15 +000020 Redistribution and use in source and binary forms, with or without
21 modification, are permitted provided that the following conditions
22 are met:
bart3c1e9d82008-06-30 17:10:29 +000023
bartbedfd232009-03-26 19:07:15 +000024 1. Redistributions of source code must retain the above copyright
25 notice, this list of conditions and the following disclaimer.
bart3c1e9d82008-06-30 17:10:29 +000026
bartbedfd232009-03-26 19:07:15 +000027 2. The origin of this software must not be misrepresented; you must
28 not claim that you wrote the original software. If you use this
29 software in a product, an acknowledgment in the product
30 documentation would be appreciated but is not required.
bart3c1e9d82008-06-30 17:10:29 +000031
bartbedfd232009-03-26 19:07:15 +000032 3. Altered source versions must be plainly marked as such, and must
33 not be misrepresented as being the original software.
bart3c1e9d82008-06-30 17:10:29 +000034
bartbedfd232009-03-26 19:07:15 +000035 4. The name of the author may not be used to endorse or promote
36 products derived from this software without specific prior written
37 permission.
bart3c1e9d82008-06-30 17:10:29 +000038
bartbedfd232009-03-26 19:07:15 +000039 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS
40 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
41 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
42 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
43 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
45 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
46 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
47 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
48 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
49 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
bart3c1e9d82008-06-30 17:10:29 +000050
bartbedfd232009-03-26 19:07:15 +000051 ----------------------------------------------------------------
bart3c1e9d82008-06-30 17:10:29 +000052
bartbedfd232009-03-26 19:07:15 +000053 Notice that the above BSD-style license applies to this one file
54 (drd.h) only. The entire rest of Valgrind is licensed under
55 the terms of the GNU General Public License, version 2. See the
56 COPYING file in the source distribution for details.
bart3c1e9d82008-06-30 17:10:29 +000057
bartbedfd232009-03-26 19:07:15 +000058 ----------------------------------------------------------------
bart3c1e9d82008-06-30 17:10:29 +000059*/
60
61#ifndef __VALGRIND_DRD_H
62#define __VALGRIND_DRD_H
63
64
65#include "valgrind.h"
66
67
bartd45d9952009-05-31 18:53:54 +000068/** Prefix for the (inline) functions defined in this header file. */
69#define DRDCL_(str) vgDrdCl_##str
70
71
72/** Obtain the thread ID assigned by Valgrind's core. */
73#define DRD_GET_VALGRIND_THREADID (DRDCL_(get_valgrind_threadid)())
74
75/** Obtain the thread ID assigned by DRD. */
76#define DRD_GET_DRD_THREADID (DRDCL_(get_drd_threadid)())
77
78/** Tell DRD not to complain about data races for the specified variable. */
79#define DRD_IGNORE_VAR(x) DRDCL_(ignore_range)(&(x), sizeof(x))
80
81/**
82 * Tell DRD to trace all memory accesses on the specified variable.
83 * until the memory that was allocated for the variable is freed.
84 */
85#define DRD_TRACE_VAR(x) DRDCL_(trace_range)(&(x), sizeof(x))
86
bart1c8cc402009-07-01 18:45:45 +000087/**
88 * @defgroup RaceDetectionAnnotations Data race detection annotations.
89 *
90 * @see See also the source file <a href="http://code.google.com/p/google-perftools/source/browse/trunk/src/base/dynamic_annotations.h">dynamic_annotations.h</a>
91 * in the ThreadSanitizer project.
92 */
93/*@{*/
bart44afe932009-06-01 10:49:38 +000094
bartd45d9952009-05-31 18:53:54 +000095/**
bartdf5a1e22009-06-03 08:11:02 +000096 * Tell DRD to insert a mark. addr is the address of an object that is not a
97 * pthread synchronization object. Inserting two 'happens before' annotations
98 * while no thread has passed by a 'happens after' annotation is an error.
bartd45d9952009-05-31 18:53:54 +000099 */
100#define ANNOTATE_HAPPENS_BEFORE(addr) DRDCL_(annotate_happens_before)(addr)
101
102/**
103 * Tell DRD that the memory accesses executed after this annotation will happen
104 * after the memory accesses performed before the most recent
bartdf5a1e22009-06-03 08:11:02 +0000105 * ANNOTATE_HAPPENS_BEFORE(addr). addr is the address of an object that is not
106 * a pthread synchronization object. Inserting a 'happens after' annotation
107 * before any other thread has passed by a 'happens before' annotation for the
108 * same address is an error.
bartd45d9952009-05-31 18:53:54 +0000109 */
110#define ANNOTATE_HAPPENS_AFTER(addr) DRDCL_(annotate_happens_after)(addr)
111
112/**
bartd45d9952009-05-31 18:53:54 +0000113 * Tell DRD that waiting on the condition variable at address cv has succeeded
114 * and a lock on the mutex at address mtx is now held. Since DRD always inserts
115 * a happens before relation between the pthread_cond_signal() or
116 * pthread_cond_broadcast() call that wakes up a pthread_cond_wait() or
117 * pthread_cond_timedwait() call and the woken up thread, this macro has been
bartdf5a1e22009-06-03 08:11:02 +0000118 * defined such that it has no effect.
bartd45d9952009-05-31 18:53:54 +0000119 */
bartdf5a1e22009-06-03 08:11:02 +0000120#define ANNOTATE_CONDVAR_LOCK_WAIT(cv, mtx) do { } while(0)
bartd45d9952009-05-31 18:53:54 +0000121
122/**
123 * Tell DRD that the condition variable at address cv is about to be signaled.
bartd45d9952009-05-31 18:53:54 +0000124 */
bartdf5a1e22009-06-03 08:11:02 +0000125#define ANNOTATE_CONDVAR_SIGNAL(cv) do { } while(0)
bartd45d9952009-05-31 18:53:54 +0000126
127/**
bartdf5a1e22009-06-03 08:11:02 +0000128 * Tell DRD that waiting on condition variable at address cv succeeded and that
129 * the memory operations performed after this annotation should be considered
130 * to happen after the matching ANNOTATE_CONDVAR_SIGNAL(cv). Since this is the
131 * default behavior of DRD, this macro and the macro above have been defined
132 * such that they have no effect.
bartd45d9952009-05-31 18:53:54 +0000133 */
bartdf5a1e22009-06-03 08:11:02 +0000134#define ANNOTATE_CONDVAR_WAIT(cv) do { } while(0)
bartd45d9952009-05-31 18:53:54 +0000135
136/**
137 * Tell DRD to consider the memory operations that happened before a mutex
138 * unlock event and after the subsequent mutex lock event on the same mutex as
bartdf5a1e22009-06-03 08:11:02 +0000139 * ordered. This is how DRD always behaves, so this macro has been defined
140 * such that it has no effect.
bartd45d9952009-05-31 18:53:54 +0000141 */
bartdf5a1e22009-06-03 08:11:02 +0000142#define ANNOTATE_MUTEX_IS_USED_AS_CONDVAR(mtx) do { } while(0)
143
144/**
145 * Tell DRD to handle the specified memory range like a pure happens-before
146 * detector would do. Since this is how DRD always behaves, this annotation
147 * has been defined such that it has no effect.
148 */
149#define ANNOTATE_PUBLISH_MEMORY_RANGE(addr, size) do { } while(0)
150
151/**
152 * Tell DRD to undo the effect of ANNOTATE_PUBLISH_MEMORY_RANGE().
153 */
154#define ANNOTATE_UNPUBLISH_MEMORY_RANGE(addr, size) do { } while(0)
bartd45d9952009-05-31 18:53:54 +0000155
156/** Tell DRD that a reader-writer lock object has been initialized. */
157#define ANNOTATE_RWLOCK_CREATE(rwlock) \
158 DRDCL_(annotate_rwlock)(rwlock, 0, 0)
159
160/** Tell DRD that a reader-writer lock object has been destroyed. */
161#define ANNOTATE_RWLOCK_DESTROY(rwlock) \
162 DRDCL_(annotate_rwlock)(rwlock, 1, 0)
163
164/**
165 * Tell DRD that a reader-writer lock has been acquired. is_w == 1 means that
166 * a write lock has been obtained, is_w == 0 means that a read lock has been
167 * obtained.
168 */
169#define ANNOTATE_RWLOCK_ACQUIRED(rwlock, is_w) \
170 DRDCL_(annotate_rwlock)(rwlock, 2, is_w)
171
172/**
bart1c8cc402009-07-01 18:45:45 +0000173 * Tell DRD that a reader lock has been acquired on a reader-writer
174 * synchronization object.
175 */
176#define ANNOTATE_READERLOCK_ACQUIRED(rwlock) ANNOTATE_RWLOCK_ACQUIRED(rwlock, 0)
177
178/**
179 * Tell DRD that a writer lock has been acquired on a reader-writer
180 * synchronization object.
181 */
182#define ANNOTATE_WRITERLOCK_ACQUIRED(rwlock) ANNOTATE_RWLOCK_ACQUIRED(rwlock, 1)
183
184/**
bartd45d9952009-05-31 18:53:54 +0000185 * Tell DRD that a reader-writer lock is about to be released. is_w == 1 means
186 * that a write lock is about to be released, is_w == 0 means that a read lock
187 * is about to be released.
188 */
189#define ANNOTATE_RWLOCK_RELEASED(rwlock, is_w) \
190 DRDCL_(annotate_rwlock)(rwlock, 3, is_w)
191
bart82c54c42009-06-03 20:01:44 +0000192/**
bart1c8cc402009-07-01 18:45:45 +0000193 * Tell DRD that a reader lock is about to be released.
194 */
195#define ANNOTATE_READERLOCK_RELEASED(rwlock) ANNOTATE_RWLOCK_RELEASED(rwlock, 0)
196
197/**
198 * Tell DRD that a writer lock is about to be released.
199 */
200#define ANNOTATE_WRITERLOCK_RELEASED(rwlock) ANNOTATE_RWLOCK_RELEASED(rwlock, 1)
201
202/**
bart82c54c42009-06-03 20:01:44 +0000203 * Tell DRD that a FIFO queue has been created. The abbreviation PCQ stands for
204 * <em>producer-consumer</em>.
205 */
bartdf5a1e22009-06-03 08:11:02 +0000206#define ANNOTATE_PCQ_CREATE(pcq) do { } while(0)
207
bart82c54c42009-06-03 20:01:44 +0000208/** Tell DRD that a FIFO queue has been destroyed. */
bartdf5a1e22009-06-03 08:11:02 +0000209#define ANNOTATE_PCQ_DESTROY(pcq) do { } while(0)
210
bart82c54c42009-06-03 20:01:44 +0000211/**
212 * Tell DRD that an element has been added to the FIFO queue at address pcq.
213 */
bartdf5a1e22009-06-03 08:11:02 +0000214#define ANNOTATE_PCQ_PUT(pcq) do { } while(0)
215
bart82c54c42009-06-03 20:01:44 +0000216/**
217 * Tell DRD that an element has been removed from the FIFO queue at address pcq,
218 * and that DRD should insert a happens-before relationship between the memory
219 * accesses that occurred before the corresponding ANNOTATE_PCQ_PUT(pcq)
220 * annotation and the memory accesses after this annotation. Correspondence
221 * between PUT and GET annotations happens in FIFO order. Since locking
222 * of the queue is needed anyway to add elements to or to remove elements from
223 * the queue, for DRD all four FIFO annotations are defined as no-ops.
224 */
bartdf5a1e22009-06-03 08:11:02 +0000225#define ANNOTATE_PCQ_GET(pcq) do { } while(0)
226
bartd45d9952009-05-31 18:53:54 +0000227/**
228 * Tell DRD that data races in the specified address range are expected and
229 * must not be reported.
230 */
231#define ANNOTATE_BENIGN_RACE(addr, descr) DRDCL_(ignore_range)(addr, 4)
232
233/** Tell DRD to ignore all reads performed by the current thread. */
234#define ANNOTATE_IGNORE_READS_BEGIN() DRDCL_(set_record_loads)(0)
235
236/** Tell DRD to no longer ignore the reads performed by the current thread. */
237#define ANNOTATE_IGNORE_READS_END() DRDCL_(set_record_loads)(1)
238
239/** Tell DRD to ignore all writes performed by the current thread. */
240#define ANNOTATE_IGNORE_WRITES_BEGIN() DRDCL_(set_record_stores)(0)
241
242/** Tell DRD to no longer ignore the writes performed by the current thread. */
243#define ANNOTATE_IGNORE_WRITES_END() DRDCL_(set_record_stores)(1)
244
245/** Tell DRD to ignore all memory accesses performed by the current thread. */
246#define ANNOTATE_IGNORE_READS_AND_WRITES_BEGIN() \
247 do { DRDCL_(set_record_loads)(0); DRD_(set_record_stores)(0); } while(0)
248
249/**
250 * Tell DRD to no longer ignore the memory accesses performed by the current
251 * thread.
252 */
253#define ANNOTATE_IGNORE_READS_AND_WRITES_END() \
254 do { DRDCL_(set_record_loads)(1); DRD_(set_record_stores)(1); } while(0)
255
256/**
257 * Tell DRD that size bytes starting at addr has been allocated by a custom
258 * memory allocator.
259 */
260#define ANNOTATE_NEW_MEMORY(addr, size) DRDCL_(clean_memory)(addr, size)
261
262/** Ask DRD to report every access to the specified address range. */
263#define ANNOTATE_TRACE_MEMORY(addr) DRDCL_(trace_range)(addr, 1)
264
265/**
266 * Tell DRD to assign the specified name to the current thread. This name will
267 * be used in error messages printed by DRD.
268 */
269#define ANNOTATE_THREAD_NAME(name) DRDCL_(set_thread_name)(name)
270
bart1c8cc402009-07-01 18:45:45 +0000271/*@}*/
bart44afe932009-06-01 10:49:38 +0000272
bartd45d9952009-05-31 18:53:54 +0000273
bart3c1e9d82008-06-30 17:10:29 +0000274/* !! ABIWARNING !! ABIWARNING !! ABIWARNING !! ABIWARNING !!
275 This enum comprises an ABI exported by Valgrind to programs
276 which use client requests. DO NOT CHANGE THE ORDER OF THESE
277 ENTRIES, NOR DELETE ANY -- add new ones at the end.
bartbedfd232009-03-26 19:07:15 +0000278*/
bartd45d9952009-05-31 18:53:54 +0000279enum {
280 /* Ask the DRD tool to discard all information about memory accesses */
281 /* and client objects for the specified range. This client request is */
282 /* binary compatible with the similarly named Helgrind client request. */
283 VG_USERREQ__DRD_CLEAN_MEMORY = VG_USERREQ_TOOL_BASE('H','G'),
284 /* args: Addr, SizeT. */
bart3c1e9d82008-06-30 17:10:29 +0000285
bartd45d9952009-05-31 18:53:54 +0000286 /* Ask the DRD tool the thread ID assigned by Valgrind. */
287 VG_USERREQ__DRD_GET_VALGRIND_THREAD_ID = VG_USERREQ_TOOL_BASE('D','R'),
288 /* args: none. */
289 /* Ask the DRD tool the thread ID assigned by DRD. */
290 VG_USERREQ__DRD_GET_DRD_THREAD_ID,
291 /* args: none. */
bart3c1e9d82008-06-30 17:10:29 +0000292
bartd45d9952009-05-31 18:53:54 +0000293 /* To tell the DRD tool to suppress data race detection on the */
294 /* specified address range. */
295 VG_USERREQ__DRD_START_SUPPRESSION,
296 /* args: start address, size in bytes */
297 /* To tell the DRD tool no longer to suppress data race detection on */
298 /* the specified address range. */
299 VG_USERREQ__DRD_FINISH_SUPPRESSION,
300 /* args: start address, size in bytes */
barte7471762009-03-11 18:51:22 +0000301
bartd45d9952009-05-31 18:53:54 +0000302 /* To ask the DRD tool to trace all accesses to the specified range. */
303 VG_USERREQ__DRD_START_TRACE_ADDR,
304 /* args: Addr, SizeT. */
305 /* To ask the DRD tool to stop tracing accesses to the specified range. */
306 VG_USERREQ__DRD_STOP_TRACE_ADDR,
307 /* args: Addr, SizeT. */
308
309 /* Tell DRD whether or not to record memory loads in the calling thread. */
310 VG_USERREQ__DRD_RECORD_LOADS,
311 /* args: Bool. */
312 /* Tell DRD whether or not to record memory stores in the calling thread. */
313 VG_USERREQ__DRD_RECORD_STORES,
314 /* args: Bool. */
315
316 /* Set the name of the thread that performs this client request. */
317 VG_USERREQ__DRD_SET_THREAD_NAME,
318 /* args: null-terminated character string. */
319
320 /* Tell DRD to insert a happens before annotation. */
321 VG_USERREQ__DRD_ANNOTATE_HAPPENS_BEFORE,
322 /* args: Addr. */
323 /* Tell DRD to insert a happens after annotation. */
324 VG_USERREQ__DRD_ANNOTATE_HAPPENS_AFTER,
325 /* args: Addr. */
bartd45d9952009-05-31 18:53:54 +0000326
327 /* Tell DRD about an operation performed on a user-defined reader-writer
328 * synchronization object. */
329 VG_USERREQ__DRD_ANNOTATE_RWLOCK,
330 /* args: Addr, Int operation_type, Int is_rw. */
331};
bart3c1e9d82008-06-30 17:10:29 +0000332
333
bartd45d9952009-05-31 18:53:54 +0000334/*
335 * Do not call the inline functions below directly but use the macro's defined
336 * above. The names of these inline functions may change from one release to
337 * another.
bart8e1033f2008-12-25 09:31:40 +0000338 */
bart8e1033f2008-12-25 09:31:40 +0000339
bart3c1e9d82008-06-30 17:10:29 +0000340static __inline__
bartd45d9952009-05-31 18:53:54 +0000341void DRDCL_(clean_memory)(const void* const addr, const int size)
342{
343 int res;
344 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_CLEAN_MEMORY,
345 addr, size, 0, 0, 0);
346}
347
348static __inline__
349int DRDCL_(get_valgrind_threadid)(void)
bart5f57be92008-07-01 08:48:56 +0000350{
bartbedfd232009-03-26 19:07:15 +0000351 int res;
352 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_GET_VALGRIND_THREAD_ID,
353 0, 0, 0, 0, 0);
354 return res;
bart5f57be92008-07-01 08:48:56 +0000355}
356
357static __inline__
bartd45d9952009-05-31 18:53:54 +0000358int DRDCL_(get_drd_threadid)(void)
bart3c1e9d82008-06-30 17:10:29 +0000359{
bartbedfd232009-03-26 19:07:15 +0000360 int res;
361 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_GET_DRD_THREAD_ID,
362 0, 0, 0, 0, 0);
363 return res;
bart3c1e9d82008-06-30 17:10:29 +0000364}
365
366static __inline__
bartd45d9952009-05-31 18:53:54 +0000367void DRDCL_(ignore_range)(const void* const addr, const int size)
bart3c1e9d82008-06-30 17:10:29 +0000368{
bartbedfd232009-03-26 19:07:15 +0000369 int res;
370 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_START_SUPPRESSION,
bartd45d9952009-05-31 18:53:54 +0000371 addr, size, 0, 0, 0);
bart3c1e9d82008-06-30 17:10:29 +0000372}
373
374static __inline__
bartd45d9952009-05-31 18:53:54 +0000375void DRDCL_(trace_range)(const void* const addr, const int size)
bart3c1e9d82008-06-30 17:10:29 +0000376{
bartbedfd232009-03-26 19:07:15 +0000377 int res;
378 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_START_TRACE_ADDR,
bartd45d9952009-05-31 18:53:54 +0000379 addr, size, 0, 0, 0);
bart3c1e9d82008-06-30 17:10:29 +0000380}
381
bartd45d9952009-05-31 18:53:54 +0000382static __inline__
383void DRDCL_(set_record_loads)(const int enabled)
384{
385 int res;
386 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_RECORD_LOADS,
387 enabled, 0, 0, 0, 0);
388}
389
390static __inline__
391void DRDCL_(set_record_stores)(const int enabled)
392{
393 int res;
394 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_RECORD_STORES,
395 enabled, 0, 0, 0, 0);
396}
397
398static __inline__
399void DRDCL_(set_thread_name)(const char* const name)
400{
401 int res;
402 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_SET_THREAD_NAME,
403 name, 0, 0, 0, 0);
404}
405
406static __inline__
407void DRDCL_(annotate_happens_before)(const void* const addr)
408{
409 int res;
410 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_ANNOTATE_HAPPENS_BEFORE,
411 addr, 0, 0, 0, 0);
412}
413
414static __inline__
415void DRDCL_(annotate_happens_after)(const void* const addr)
416{
417 int res;
418 VALGRIND_DO_CLIENT_REQUEST(res, 0, VG_USERREQ__DRD_ANNOTATE_HAPPENS_AFTER,
419 addr, 0, 0, 0, 0);
420}
421
422static __inline__
bartd45d9952009-05-31 18:53:54 +0000423void DRDCL_(annotate_rwlock)(const void* const rwlock, const int op,
424 const int is_w)
425{
426 int res;
427 VALGRIND_DO_CLIENT_REQUEST(res, 0,
428 VG_USERREQ__DRD_ANNOTATE_RWLOCK,
429 rwlock, op, is_w, 0, 0);
430}
bart3c1e9d82008-06-30 17:10:29 +0000431
432#endif /* __VALGRIND_DRD_H */