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 25Archer is distributed under the terms of the Apache License. 26 27Please see LICENSE.txt for usage terms. 28 29LLNL-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 36detection. 37This avoids false alerts in data race detection. 38Archer is automatically loaded for OpenMP applications which are compiled 39with ThreadSanitizer option. 40 41<a id="org9a459f1"></a> 42 43# Build Archer within Clang/LLVM 44 45This distribution of Archer is automatically built with the OpenMP runtime 46and 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 57To 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 63To 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 73TSan runtime flags are passed via **TSAN_OPTIONS** environment variable, 74we highly recommend the following option to avoid false alerts for the 75OpenMP or MPI runtime implementation: 76 77 export TSAN_OPTIONS="ignore_noninstrumented_modules=1" 78 79 80Runtime flags are passed via **ARCHER_OPTIONS** environment variable, 81different 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_shadow</td> 106<td class="org-right">0</td> 107<td class="org-left">Flush shadow memory at the end of an outer OpenMP 108parallel region. Our experiments show that this can reduce memory overhead 109by ~30% and runtime overhead by ~10%. This flag is useful for large OpenMP 110applications that typically require large amounts of memory, causing 111out-of-memory exceptions when checked by Archer.</td> 112</tr> 113</tbody> 114 115<tbody> 116<tr> 117<td class="org-left">print_max_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_serial</td> 126<td class="org-right">0</td> 127<td class="org-left">Turn off tracking and analysis of memory accesses in 128the sequential part of an OpenMP program. (Only effective when OpenMP 129runtime is initialized. In doubt, insert omp_get_max_threads() as first 130statement in main!)</td> 131</tr> 132</tbody> 133 134<tbody> 135<tr> 136<td class="org-left">all_memory</td> 137<td class="org-right">0</td> 138<td class="org-left">Turn on tracking and analysis of omp_all_memory 139dependencies. Archer will activate the support automatically when 140such dependency is seen during execution. At this time the analysis 141already missed synchronization semantics, which will lead to false 142reports in most cases.</td> 143</tr> 144</tbody> 145 146<tbody> 147<tr> 148<td class="org-left">report_data_leak</td> 149<td class="org-right">0</td> 150<td class="org-left">Report leaking OMPT data for execution under 151Archer. 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 177Let us take the program below and follow the steps to compile and 178check the program for data races. 179 180Suppose 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 196We compile the program as follow: 197 198 clang -fsanitize=thread -fopenmp -g myprogram.c -o myprogram 199 200Now we can run the program with the following commands: 201 202 export OMP_NUM_THREADS=2 203 ./myprogram 204 205Archer will output a report in case it finds data races. In our case 206the 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 244