From: Bart Van Assche Date: Tue, 1 Jul 2008 13:43:44 +0000 (+0000) Subject: Continued working on the DRD documentation. X-Git-Tag: svn/VALGRIND_3_4_0~395 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f46a4538edbe0039daffe407137bef40688475ef;p=thirdparty%2Fvalgrind.git Continued working on the DRD documentation. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@8329 --- diff --git a/exp-drd/docs/drd-manual.xml b/exp-drd/docs/drd-manual.xml index fec377b5ec..5a098b7506 100644 --- a/exp-drd/docs/drd-manual.xml +++ b/exp-drd/docs/drd-manual.xml @@ -805,6 +805,103 @@ output reports that the lock acquired at line 51 in source file + +There is one message that needs further explanation, namely sending a +signal to a condition variable while no lock is held on the mutex +associated with the signal. Consider e.g. the example . In this example the +code in thread 1 passes if flag != 0, or waits +until it has been signaled by thread 2. If however the code of thread +1 is scheduled after the pthread_mutex_unlock() +call in thread 2 and before thread 2 calls +pthread_cond_signal(), thread 1 will block +indefinitely. The code in the example never blocks indefinitely. + + + +Because most calls of pthread_cond_signal() or +pthread_cond_broadcast() while no lock is held on +the mutex associated with the condition variable are racy, by default +DRD reports such calls. + + + +Racy use of pthread_cond_wait() + + + + + + Thread 1 + Thread 2 + + + + + + + + + + + + + +
+ + +Correct use of pthread_cond_wait() + + + + + + Thread 1 + Thread 2 + + + + + + + + + + + + + +
+ @@ -812,8 +909,81 @@ output reports that the lock acquired at line 51 in source file Client Requests -Just as for other Valgrind tools it is possible to pass information -from a client program to the DRD tool. +Just as for other Valgrind tools it is possible to let a client +program interact with the DRD tool. + + + +The interface between client programs and the DRD tool is defined in +the header file <valgrind/drd.h>. The +available client requests are: + + + + VG_USERREQ__DRD_GET_VALGRIND_THREAD_ID. + Query the thread ID that was assigned by the Valgrind core to + the thread executing this client request. Valgrind's thread ID's + start at one and are recycled in case a thread stops. + + + + + VG_USERREQ__DRD_GET_DRD_THREAD_ID. + Query the thread ID that was assigned by DRD to + the thread executing this client request. DRD's thread ID's + start at one and are never recycled. + + + + + VG_USERREQ__DRD_START_SUPPRESSION. Some + applications contain intentional races. There exist + e.g. applications where the same value is assigned to a shared + variable from two different threads. It may be more convenient + to suppress such races than to solve these. This client request + allows to suppress such races. See also the macro + DRD_IGNORE_VAR(x) defined in + <valgrind/drd.h>. + + + + + VG_USERREQ__DRD_FINISH_SUPPRESSION. Tell DRD + to no longer ignore data races in the address range that was + suppressed via + VG_USERREQ__DRD_START_SUPPRESSION. + + + + + VG_USERREQ__DRD_START_TRACE_ADDR. Trace all + load and store activity on the specified address range. When DRD + reports a data race on a specified variable, and it's not + immediately clear which source code statements triggered the + conflicting accesses, it can be helpful to trace all activity on + the offending memory location. See also the macro + DRD_TRACE_VAR(x) defined in + <valgrind/drd.h>. + + + + + VG_USERREQ__DRD_STOP_TRACE_ADDR. Do no longer + trace load and store activity for the specified address range. + range. + + + + + + +Note: if you compiled Valgrind yourself, the header file +<valgrind/drd.h> will have been installed in +the directory /usr/include by the command +make install. If you obtained Valgrind by +installing it as a package however, you will probably have to install +another package with a name like valgrind-devel +before Valgrind's header files are present. @@ -822,6 +992,87 @@ from a client program to the DRD tool. Debugging OpenMP Programs With DRD + +OpenMP stands for Open Multi-Processing. The +OpenMP standard consists of a set of compiler directives for C, C++ +and Fortran programs that allows a compiler to transform a sequential +program into a parallel program. OpenMP is well suited for HPC +applications and allows to work at a higher level compared to direct +use of the POSIX threads API. While OpenMP ensures that the POSIX API +is used correctly, OpenMP programs can still contain data races. So it +makes sense to verify OpenMP programs with a thread checking tool. + + + +DRD supports OpenMP shared-memory programs generated by gcc. The gcc +compiler supports OpenMP since version 4.2.0. Gcc's runtime support +for OpenMP programs is provided by a library called +libgomp. The synchronization primites implemented +in this library use Linux' futex system call directly, unless the +library has been configured with the +--disable-linux-futex flag. DRD only supports +libgomp libraries that have been configured with this flag and in +which symbol information is present. For most Linux distributions this +means that you will have to recompile gcc. See also the script +exp-drd/scripts/download-and-build-gcc in the +Valgrind source tree for an example of how to compile gcc. You will +also have to make sure that the newly compiled +libgomp.so library is loaded when OpenMP programs +are started. This is possible by adding a line similar to the +following to your shell startup script: + + + + +As an example, the test OpenMP test program +exp-drd/scripts/omp_matinv triggers a data race +when the option -r has been specified on the command line. The data +race is triggered by the following code: + + + + +The above code is racy because the variable k has +not been declared private. DRD will print the following error message +for the above code: + + + +In the above output the function name gj.omp_fn.0 +has been generated by gcc from the function name +gj. Unfortunately the variable name +(k) is not shown as the allocation context -- it is +not clear to me whether this is caused by Valgrind or whether this is +caused by gcc. The most usable information in the above output is the +source file name and the line number where the data race has been detected +(omp_matinv.c:203). + + For more information about OpenMP, see also openmp.org. @@ -853,14 +1104,6 @@ For more information about OpenMP, see also LinuxThreads library is not supported. - - - When running DRD on a PowerPC CPU, DRD will report false - positives on atomic operations. See also Valgrind bug - 162354. - - DRD, just like memcheck, will refuse to start on Linux