openmp/tools/archer/README.md

   1 <div id="table-of-contents">
   2 <h2>Table of Contents</h2>
   3 <div id="text-table-of-contents">
   4 <ul>
   5 <li><a href="#org8ca70b5">1. License</a></li>
   6 <li><a href="#orgc6a2b10">2. Introduction</a></li>
   7 <li><a href="#org9a459f1">3. Installation</a></li>
   8 <li><a href="#orgb820ad0">4. Usage</a>
   9 <ul>
  10 <li><a href="#org213ff1a">4.1. How to compile</a></li>
  11 <li><a href="#org110062c">4.2. Runtime Flags</a></li>
  12 </ul>
  13 </li>
  14 <li><a href="#org73e58a9">5. Example</a></li>
  15 <li><a href="#orgcc38a36">6. Contacts and Support</a></li>
  16 </ul>
  17 </div>
  18 </div>
  19
  20
  21 <a id="org8ca70b5"></a>
  22
  23 # License
  24
  25 Archer is distributed under the terms of the Apache License.
  26
  27 Please see LICENSE.txt for usage terms.
  28
  29 LLNL-CODE-773957
  30
  31 <a id="orgc6a2b10"></a>
  32
  33 # Introduction
  34
  35 **Archer** is an OMPT tool which annotates OpenMP synchronization semantics for data race
  36 detection.
  37 This avoids false alerts in data race detection.
  38 Archer is automatically loaded for OpenMP applications which are compiled
  39 with ThreadSanitizer option.
  40
  41 <a id="org9a459f1"></a>
  42
  43 # Build Archer within Clang/LLVM
  44
  45 This distribution of Archer is automatically built with the OpenMP runtime
  46 and automatically loaded by the OpenMP runtime.
  47
  48 <a id="orgb820ad0"></a>
  49
  50 # Usage
  51
  52
  53 <a id="org213ff1a"></a>
  54
  55 ## How to compile
  56
  57 To use archer, compile the application with the extra flag
  58 `-fsanitize=thread`:
  59
  60     clang -O3 -g -fopenmp -fsanitize=thread app.c
  61     clang++ -O3 -g -fopenmp -fsanitize=thread app.cpp
  62
  63 To compile Fortran applications, compile with gfortran, link with clang:
  64
  65     gfortran -g -c -fopenmp -fsanitize=thread app.f
  66     clang -fopenmp -fsanitize=thread app.o -lgfortran
  67
  68
  69 <a id="org110062c"></a>
  70
  71 ## Runtime Flags
  72
  73 TSan runtime flags are passed via **TSAN&#95;OPTIONS** environment variable,
  74 we highly recommend the following option to avoid false alerts for the
  75 OpenMP or MPI runtime implementation:
  76
  77     export TSAN_OPTIONS="ignore_noninstrumented_modules=1"
  78
  79
  80 Runtime flags are passed via **ARCHER&#95;OPTIONS** environment variable,
  81 different flags are separated by spaces, e.g.:
  82
  83     ARCHER_OPTIONS="flush_shadow=1" ./myprogram
  84
  85 <table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
  86
  87
  88 <colgroup>
  89 <col  class="org-left" />
  90
  91 <col  class="org-right" />
  92
  93 <col  class="org-left" />
  94 </colgroup>
  95 <thead>
  96 <tr>
  97 <th scope="col" class="org-left">Flag Name</th>
  98 <th scope="col" class="org-right">Default value</th>
  99 <th scope="col" class="org-left">Description</th>
 100 </tr>
 101 </thead>
 102
 103 <tbody>
 104 <tr>
 105 <td class="org-left">flush&#95;shadow</td>
 106 <td class="org-right">0</td>
 107 <td class="org-left">Flush shadow memory at the end of an outer OpenMP
 108 parallel region. Our experiments show that this can reduce memory overhead
 109 by ~30% and runtime overhead by ~10%. This flag is useful for large OpenMP
 110 applications that typically require large amounts of memory, causing
 111 out-of-memory exceptions when checked by Archer.</td>
 112 </tr>
 113 </tbody>
 114
 115 <tbody>
 116 <tr>
 117 <td class="org-left">print&#95;max&#95;rss</td>
 118 <td class="org-right">0</td>
 119 <td class="org-left">Print the RSS memory peak at the end of the execution.</td>
 120 </tr>
 121 </tbody>
 122
 123 <tbody>
 124 <tr>
 125 <td class="org-left">ignore&#95;serial</td>
 126 <td class="org-right">0</td>
 127 <td class="org-left">Turn off tracking and analysis of memory accesses in
 128 the sequential part of an OpenMP program. (Only effective when OpenMP
 129 runtime is initialized. In doubt, insert omp_get_max_threads() as first
 130 statement in main!)</td>
 131 </tr>
 132 </tbody>
 133
 134 <tbody>
 135 <tr>
 136 <td class="org-left">all&#95;memory</td>
 137 <td class="org-right">0</td>
 138 <td class="org-left">Turn on tracking and analysis of omp_all_memory
 139 dependencies. Archer will activate the support automatically when
 140 such dependency is seen during execution. At this time the analysis
 141 already missed synchronization semantics, which will lead to false
 142 reports in most cases.</td>
 143 </tr>
 144 </tbody>
 145
 146 <tbody>
 147 <tr>
 148 <td class="org-left">report&#95;data&#95;leak</td>
 149 <td class="org-right">0</td>
 150 <td class="org-left">Report leaking OMPT data for execution under
 151 Archer. Used for testing and debugging Archer if errors occur.</td>
 152 </tr>
 153 </tbody>
 154
 155 <tbody>
 156 <tr>
 157 <td class="org-left">verbose</td>
 158 <td class="org-right">0</td>
 159 <td class="org-left">Print startup information.</td>
 160 </tr>
 161 </tbody>
 162
 163 <tbody>
 164 <tr>
 165 <td class="org-left">enable</td>
 166 <td class="org-right">1</td>
 167 <td class="org-left">Use Archer runtime library during execution.</td>
 168 </tr>
 169 </tbody>
 170 </table>
 171
 172
 173 <a id="org73e58a9"></a>
 174
 175 # Example
 176
 177 Let us take the program below and follow the steps to compile and
 178 check the program for data races.
 179
 180 Suppose our program is called *myprogram.c*:
 181
 182      1  #include <stdio.h>
 183      2
 184      3  #define N 1000
 185      4
 186      5  int main (int argc, char **argv)
 187      6  {
 188      7    int a[N];
 189      8
 190      9  #pragma omp parallel for
 191     10    for (int i = 0; i < N - 1; i++) {
 192     11      a[i] = a[i + 1];
 193     12    }
 194     13  }
 195
 196 We compile the program as follow:
 197
 198     clang -fsanitize=thread -fopenmp -g myprogram.c -o myprogram
 199
 200 Now we can run the program with the following commands:
 201
 202     export OMP_NUM_THREADS=2
 203     ./myprogram
 204
 205 Archer will output a report in case it finds data races. In our case
 206 the report will look as follow:
 207
 208     ==================
 209     WARNING: ThreadSanitizer: data race (pid=13641)
 210       Read of size 4 at 0x7fff79a01170 by main thread:
 211         #0 .omp_outlined. myprogram.c:11:12 (myprogram+0x00000049b5a2)
 212         #1 __kmp_invoke_microtask <null> (libomp.so+0x000000077842)
 213         #2 __libc_start_main /build/glibc-t3gR2i/glibc-2.23/csu/../csu/libc-start.c:291 (libc.so.6+0x00000002082f)
 214
 215       Previous write of size 4 at 0x7fff79a01170 by thread T1:
 216         #0 .omp_outlined. myprogram.c:11:10 (myprogram+0x00000049b5d6)
 217         #1 __kmp_invoke_microtask <null> (libomp.so+0x000000077842)
 218
 219       Location is stack of main thread.
 220
 221       Thread T1 (tid=13643, running) created by main thread at:
 222         #0 pthread_create tsan_interceptors.cc:902:3 (myprogram+0x00000043db75)
 223         #1 __kmp_create_worker <null> (libomp.so+0x00000006c364)
 224         #2 __libc_start_main /build/glibc-t3gR2i/glibc-2.23/csu/../csu/libc-start.c:291 (libc.so.6+0x00000002082f)
 225
 226     SUMMARY: ThreadSanitizer: data race myprogram.c:11:12 in .omp_outlined.
 227     ==================
 228     ThreadSanitizer: reported 1 warnings
 229
 230
 231 <a id="orgcc38a36"></a>
 232
 233 # Contacts and Support
 234
 235 -   [Google group](https://groups.google.com/forum/#!forum/archer-pruner)
 236 -   [Slack Channel](https://pruners.slack.com)
 237
 238     <ul style="list-style-type:circle"> <li> For an invitation please write an email to <a href="mailto:simone@cs.utah.edu?Subject=[archer-slack] Slack Invitation" target="_top">Simone Atzeni</a> with a reason why you want to be part of the PRUNERS Slack Team. </li> </ul>
 239 -   E-Mail Contacts:
 240
 241     <ul style="list-style-type:circle"> <li> <a href="mailto:simone@cs.utah.edu?Subject=[archer-dev]%20" target="_top">Simone Atzeni</a> </li> <li> <a href="mailto:protze@itc.rwth-aachen.de?Subject=[archer-dev]%20" target="_top">Joachim Protze</a> </li> </ul>
 242
 243