[cfe-commits] r156910 - /cfe/trunk/docs/ThreadSanitizer.html

Wed May 16 01:14:36 PDT 2012

Author: kcc
Date: Wed May 16 03:14:36 2012
New Revision: 156910

URL: http://llvm.org/viewvc/llvm-project?rev=156910&view=rev
Log:
[tsan] first version of ThreadSanitizer docs

Added:
    cfe/trunk/docs/ThreadSanitizer.html

Added: cfe/trunk/docs/ThreadSanitizer.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ThreadSanitizer.html?rev=156910&view=auto
==============================================================================

--- cfe/trunk/docs/ThreadSanitizer.html (added)
+++ cfe/trunk/docs/ThreadSanitizer.html Wed May 16 03:14:36 2012
@@ -0,0 +1,125 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
+          "http://www.w3.org/TR/html4/strict.dtd">
+<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
+<html>
+<head>
+  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+  <title>ThreadSanitizer, a race detector</title>
+  <link type="text/css" rel="stylesheet" href="../menu.css">
+  <link type="text/css" rel="stylesheet" href="../content.css">
+  <style type="text/css">
+    td {
+            vertical-align: top;
+    }
+  </style>
+</head>
+<body>
+
+<!--#include virtual="../menu.html.incl"-->
+
+<div id="content">
+
+<h1>ThreadSanitizer</h1>
+<ul>
+  <li> <a href="#intro">Introduction</a>
+  <li> <a href="#howtobuild">How to Build</a>
+  <li> <a href="#platforms">Supported Platforms</a>
+  <li> <a href="#usage">Usage</a>
+  <li> <a href="#limitations">Limitations</a>
+  <li> <a href="#status">Current Status</a>
+  <li> <a href="#moreinfo">More Information</a>
+</ul>
+
+<h2 id="intro">Introduction</h2>
+ThreadSanitizer is a tool that detects data races. <BR>
+It consists of a compiler instrumentation module and a run-time library. <BR>
+Typical slowdown introduced by ThreadSanitizer is <b>5x-15x</b> (TODO: these numbers are
+aproximate so far).
+
+<h2 id="howtobuild">How to build</h2>
+Follow the <a href="../get_started.html">clang build instructions</a>. <BR>
+Note: CMake build does not work yet.
+See <a href="http://llvm.org/bugs/show_bug.cgi?id=12272">bug 12272</a>.
+
+<h2 id="platforms">Supported Platforms</h2>
+ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04). <BR>
+Support for MacOS 10.7 (64-bit only) is planed for late 2012. <BR>
+Support for 32-bit platforms is problematic and not yet planed.
+
+
+
+<h2 id="usage">Usage</h2>
+Simply compile your program with <tt>-faddress-sanitizer -fPIE</tt> and link it
+with <tt>-faddress-sanitizer -pie</tt>.<BR>
+To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
+Use <tt>-g</tt> to get file names and line numbers in the warning messages. <BR>
+
+Example:
+<pre>
+% cat projects/compiler-rt/lib/tsan/output_tests/tiny_race.c
+#include <pthread.h>
+int Global;
+void *Thread1(void *x) {
+  Global = 42;
+  return x;
+}
+int main() {
+  pthread_t t;
+  pthread_create(&t, NULL, Thread1, NULL);
+  Global = 43;
+  pthread_join(t, NULL);
+  return Global;
+}
+</pre>
+
+<pre>
+% clang -fthread-sanitizer -g -O1 tiny_race.c -fPIE -pie
+</pre>
+
+If a bug is detected, the program will print an error message to stderr.
+Currently, ThreadSanitizer symbolizes its output using an external
+<tt>addr2line</tt>
+process (this will be fixed in future).
+<pre>
+% TSAN_OPTIONS=strip_path_prefix=`pwd`/  # Don't print full paths.
+% ./a.out 2> log
+% cat log
+WARNING: ThreadSanitizer: data race (pid=19219)
+  Write of size 4 at 0x7fcf47b21bc0 by thread 1:
+    #0 Thread1 tiny_race.c:4 (exe+0x00000000a360)
+  Previous write of size 4 at 0x7fcf47b21bc0 by main thread:
+    #0 main tiny_race.c:10 (exe+0x00000000a3b4)
+  Thread 1 (running) created at:
+    #0 pthread_create ??:0 (exe+0x00000000c790)
+    #1 main tiny_race.c:9 (exe+0x00000000a3a4)
+</pre>
+
+
+<h2 id="limitations">Limitations</h2>
+<ul>
+<li> ThreadSanitizer uses more real memory than a native run.
+At the default settings the memory overhead is 9x plus 9Mb per each thread.
+Settings with 5x and 3x overhead (but less accurate analysis) are also available.
+<li> ThreadSanitizer maps (but not reserves) a lot of virtual address space.
+This means that tools like <tt>ulimit</tt> may not work as usually expected.
+<li> Static linking is not supported.
+<li> ThreadSanitizer requires <tt>-fPIE -pie</tt>
+</ul>
+
+
+<h2 id="status">Current Status</h2>
+ThreadSanitizer is in alpha stage.
+It is known to work on large C++ programs using pthreads, but we do not promise
+anything (yet). <BR>
+C++11 threading is not yet supported.
+
+We are actively working on enhancing the tool -- stay tuned.
+Any help, especially in the form of minimized standalone tests is more than welcome.
+
+<h2 id="moreinfo">More Information</h2>
+<a href="http://code.google.com/p/thread-sanitizer/">http://code.google.com/p/thread-sanitizer</a>.
+
+
+</div>
+</body>
+</html>



