1 files changed, 95 insertions, 0 deletions
diff --git a/clang/docs/ThreadSanitizer.rst b/clang/docs/ThreadSanitizer.rst
new file mode 100644
index 00000000000..5f04170da67
--- /dev/null
+++ b/clang/docs/ThreadSanitizer.rst
@@ -0,0 +1,95 @@
+ThreadSanitizer
+===============
+
+Introduction
+------------
+
+ThreadSanitizer is a tool that detects data races.  It consists of a compiler
+instrumentation module and a run-time library.  Typical slowdown introduced by
+ThreadSanitizer is **5x-15x** (TODO: these numbers are approximate so far).
+
+How to build
+------------
+
+Follow the `Clang build instructions <../get_started.html>`_.  CMake build is
+supported.
+
+Supported Platforms
+-------------------
+
+ThreadSanitizer is supported on Linux x86_64 (tested on Ubuntu 10.04).  Support
+for MacOS 10.7 (64-bit only) is planned for late 2012.  Support for 32-bit
+platforms is problematic and not yet planned.
+
+Usage
+-----
+
+Simply compile your program with ``-fsanitize=thread -fPIE`` and link it with
+``-fsanitize=thread -pie``.  To get a reasonable performance add ``-O1`` or
+higher.  Use ``-g`` to get file names and line numbers in the warning messages.
+
+Example:
+
+.. code-block:: c++
+
+  % 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;
+  }
+
+  $ clang -fsanitize=thread -g -O1 tiny_race.c -fPIE -pie
+
+If a bug is detected, the program will print an error message to stderr.
+Currently, ThreadSanitizer symbolizes its output using an external
+``addr2line`` process (this will be fixed in future).
+
+.. code-block:: bash
+
+  % 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)
+
+Limitations
+-----------
+
+* 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.
+* ThreadSanitizer maps (but does not reserve) a lot of virtual address space.
+  This means that tools like ``ulimit`` may not work as usually expected.
+* Static linking is not supported.
+* ThreadSanitizer requires ``-fPIE -pie``.
+
+Current Status
+--------------
+
+ThreadSanitizer is in alpha stage.  It is known to work on large C++ programs
+using pthreads, but we do not promise anything (yet).  C++11 threading is not
+yet supported.  The test suite is integrated into CMake build and can be run
+with ``make check-tsan`` command.
+
+We are actively working on enhancing the tool --- stay tuned.  Any help,
+especially in the form of minimized standalone tests is more than welcome.
+
+More Information
+----------------
+`http://code.google.com/p/thread-sanitizer <http://code.google.com/p/thread-sanitizer/>`_.
+