| <div id="table-of-contents"> |
| <h2>Table of Contents</h2> |
| <div id="text-table-of-contents"> |
| <ul> |
| <li><a href="#org8ca70b5">1. License</a></li> |
| <li><a href="#orgc6a2b10">2. Introduction</a></li> |
| <li><a href="#org9a459f1">3. Installation</a></li> |
| <li><a href="#orgb820ad0">4. Usage</a> |
| <ul> |
| <li><a href="#org213ff1a">4.1. How to compile</a></li> |
| <li><a href="#org110062c">4.2. Runtime Flags</a></li> |
| </ul> |
| </li> |
| <li><a href="#org73e58a9">5. Example</a></li> |
| <li><a href="#orgcc38a36">6. Contacts and Support</a></li> |
| </ul> |
| </div> |
| </div> |
| |
| |
| <a id="org8ca70b5"></a> |
| |
| # License |
| |
| Archer is distributed under the terms of the Apache License. |
| |
| Please see LICENSE.txt for usage terms. |
| |
| LLNL-CODE-773957 |
| |
| <a id="orgc6a2b10"></a> |
| |
| # Introduction |
| |
| **Archer** is an OMPT tool which annotates OpenMP synchronization semantics for data race |
| detection. |
| This avoids false alerts in data race detection. |
| Archer is automatically loaded for OpenMP applications which are compiled |
| with ThreadSanitizer option. |
| |
| <a id="org9a459f1"></a> |
| |
| # Build Archer within Clang/LLVM |
| |
| This distribution of Archer is automatically built with the OpenMP runtime |
| and automatically loaded by the OpenMP runtime. |
| |
| <a id="orgb820ad0"></a> |
| |
| # Usage |
| |
| |
| <a id="org213ff1a"></a> |
| |
| ## How to compile |
| |
| To use archer, compile the application with the extra flag |
| `-fsanitize=thread`: |
| |
| clang -O3 -g -fopenmp -fsanitize=thread app.c |
| clang++ -O3 -g -fopenmp -fsanitize=thread app.cpp |
| |
| To compile Fortran applications, compile with gfortran, link with clang: |
| |
| gfortran -g -c -fopenmp -fsanitize=thread app.f |
| clang -fopenmp -fsanitize=thread app.o -lgfortran |
| |
| |
| <a id="org110062c"></a> |
| |
| ## Runtime Flags |
| |
| TSan runtime flags are passed via **TSAN_OPTIONS** environment variable, |
| we highly recommend the following option to avoid false alerts for the |
| OpenMP or MPI runtime implementation: |
| |
| export TSAN_OPTIONS="ignore_noninstrumented_modules=1" |
| |
| |
| Runtime flags are passed via **ARCHER_OPTIONS** environment variable, |
| different flags are separated by spaces, e.g.: |
| |
| ARCHER_OPTIONS="flush_shadow=1" ./myprogram |
| |
| <table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"> |
| |
| |
| <colgroup> |
| <col class="org-left" /> |
| |
| <col class="org-right" /> |
| |
| <col class="org-left" /> |
| </colgroup> |
| <thead> |
| <tr> |
| <th scope="col" class="org-left">Flag Name</th> |
| <th scope="col" class="org-right">Default value</th> |
| <th scope="col" class="org-left">Description</th> |
| </tr> |
| </thead> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">flush_shadow</td> |
| <td class="org-right">0</td> |
| <td class="org-left">Flush shadow memory at the end of an outer OpenMP |
| parallel region. Our experiments show that this can reduce memory overhead |
| by ~30% and runtime overhead by ~10%. This flag is useful for large OpenMP |
| applications that typically require large amounts of memory, causing |
| out-of-memory exceptions when checked by Archer.</td> |
| </tr> |
| </tbody> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">print_max_rss</td> |
| <td class="org-right">0</td> |
| <td class="org-left">Print the RSS memory peak at the end of the execution.</td> |
| </tr> |
| </tbody> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">ignore_serial</td> |
| <td class="org-right">0</td> |
| <td class="org-left">Turn off tracking and analysis of memory accesses in |
| the sequential part of an OpenMP program. (Only effective when OpenMP |
| runtime is initialized. In doubt, insert omp_get_max_threads() as first |
| statement in main!)</td> |
| </tr> |
| </tbody> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">all_memory</td> |
| <td class="org-right">0</td> |
| <td class="org-left">Turn on tracking and analysis of omp_all_memory |
| dependencies. Archer will activate the support automatically when |
| such dependency is seen during execution. At this time the analysis |
| already missed synchronization semantics, which will lead to false |
| reports in most cases.</td> |
| </tr> |
| </tbody> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">report_data_leak</td> |
| <td class="org-right">0</td> |
| <td class="org-left">Report leaking OMPT data for execution under |
| Archer. Used for testing and debugging Archer if errors occur.</td> |
| </tr> |
| </tbody> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">verbose</td> |
| <td class="org-right">0</td> |
| <td class="org-left">Print startup information.</td> |
| </tr> |
| </tbody> |
| |
| <tbody> |
| <tr> |
| <td class="org-left">enable</td> |
| <td class="org-right">1</td> |
| <td class="org-left">Use Archer runtime library during execution.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| |
| <a id="org73e58a9"></a> |
| |
| # Example |
| |
| Let us take the program below and follow the steps to compile and |
| check the program for data races. |
| |
| Suppose our program is called *myprogram.c*: |
| |
| 1 #include <stdio.h> |
| 2 |
| 3 #define N 1000 |
| 4 |
| 5 int main (int argc, char **argv) |
| 6 { |
| 7 int a[N]; |
| 8 |
| 9 #pragma omp parallel for |
| 10 for (int i = 0; i < N - 1; i++) { |
| 11 a[i] = a[i + 1]; |
| 12 } |
| 13 } |
| |
| We compile the program as follow: |
| |
| clang -fsanitize=thread -fopenmp -g myprogram.c -o myprogram |
| |
| Now we can run the program with the following commands: |
| |
| export OMP_NUM_THREADS=2 |
| ./myprogram |
| |
| Archer will output a report in case it finds data races. In our case |
| the report will look as follow: |
| |
| ================== |
| WARNING: ThreadSanitizer: data race (pid=13641) |
| Read of size 4 at 0x7fff79a01170 by main thread: |
| #0 .omp_outlined. myprogram.c:11:12 (myprogram+0x00000049b5a2) |
| #1 __kmp_invoke_microtask <null> (libomp.so+0x000000077842) |
| #2 __libc_start_main /build/glibc-t3gR2i/glibc-2.23/csu/../csu/libc-start.c:291 (libc.so.6+0x00000002082f) |
| |
| Previous write of size 4 at 0x7fff79a01170 by thread T1: |
| #0 .omp_outlined. myprogram.c:11:10 (myprogram+0x00000049b5d6) |
| #1 __kmp_invoke_microtask <null> (libomp.so+0x000000077842) |
| |
| Location is stack of main thread. |
| |
| Thread T1 (tid=13643, running) created by main thread at: |
| #0 pthread_create tsan_interceptors.cc:902:3 (myprogram+0x00000043db75) |
| #1 __kmp_create_worker <null> (libomp.so+0x00000006c364) |
| #2 __libc_start_main /build/glibc-t3gR2i/glibc-2.23/csu/../csu/libc-start.c:291 (libc.so.6+0x00000002082f) |
| |
| SUMMARY: ThreadSanitizer: data race myprogram.c:11:12 in .omp_outlined. |
| ================== |
| ThreadSanitizer: reported 1 warnings |
| |
| |
| <a id="orgcc38a36"></a> |
| |
| # Contacts and Support |
| |
| - [Google group](https://groups.google.com/forum/#!forum/archer-pruner) |
| - [Slack Channel](https://pruners.slack.com) |
| |
| <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> |
| - E-Mail Contacts: |
| |
| <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> |
| |
| |
