[19/19] docs: Added details on TSan to testing.rst

Commit Message

Robert Foley May 22, 2020, 4:07 p.m. UTC

This includes details on how to build and test with TSan
both inside a docker and outside.

Signed-off-by: Robert Foley <[e-mail]>
---
 docs/devel/testing.rst | 72 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

Comments

Emilio Cota May 23, 2020, 8:29 p.m. UTC | #1

On Fri, May 22, 2020 at 12:07:55 -0400, Robert Foley wrote:
> This includes details on how to build and test with TSan
> both inside a docker and outside.
> 
> Signed-off-by: Robert Foley <[e-mail]>

Reviewed-by: Emilio G. Cota <[e-mail]>

		E.

Patch

diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
index 770a987ea4..5b0a828068 100644
--- a/docs/devel/testing.rst
+++ b/docs/devel/testing.rst
@@ -397,6 +397,78 @@  list is in the ``make docker`` help text. The frequently used ones are:
 * ``DEBUG=1``: enables debug. See the previous "Debugging a Docker test
   failure" section.
 
+Thread Sanitizer
+================
+TSan is currently supported in the ubuntu2004 docker.
+
+Just add the TSAN=1 argument to use TSan
+
+.. code::
+
+  make docker-test-build@ubuntu2004 TSAN=1
+
+or
+
+.. code::
+  
+  make docker-test-quick@ubuntu2004 TSAN=1
+
+The runtime behavior or TSAN is controlled by the TSAN_OPTIONS environment
+variable.  We set this variable automatically to for example, maximize
+the number of warnings TSan can find and also to specify the location of
+the files with TSan warnings.  
+
+TSan warnings are placed in files located at build/tsan/.
+
+We recommend using DEBUG=1 to allow launching the test from inside the docker,
+and to allow review of the warnings generated by TSan.
+A few important files to note are:
+
+tests/tsan/suppressions.tsan - Has TSan warnings we wish to suppress at runtime.
+In some cases we choose to put suppressions here since the resolution is
+slightly finer than the blacklist, since we can disable by warning type.
+
+tests/tsan/blacklist.tsan - Has TSan warnings we wish to disable
+at compile time.
+
+include/qemu/tsan.h - Defines various annotations which can also be used
+to give TSan more information some example uses are to allow suppressing
+TSan warnings, or annotating thread names so they show up properly in
+the TSan warnings.
+
+TSan without docker
+-------------------
+
+It is possible to build and test with TSan outside of a docker, but with a
+few additional steps required.
+These steps are normally done automatically in the docker.
+
+First, to configure the build for TSan:
+
+.. code::
+
+  ../configure --enable-tsan --cc=clang-10 --cxx=clang++-10 \
+               --disable-werror --extra-cflags="-O0"
+
+There is also a one time patch needed in clang-9 or clang-10:
+
+.. code::
+
+  sed -i 's/^const/static const/g' \
+      /usr/lib/llvm-10/lib/clang/10.0.0/include/sanitizer/tsan_interface.h
+
+When running tests, the TSAN_OPTIONS environment variable needs to be set.
+
+.. code::
+
+  export TSAN_OPTIONS=suppressions=<path to qemu>/tests/tsan/suppressions.tsan \
+         detect_deadlocks=false history_size=7 exitcode=0 \
+         log_path=<build path>/tsan/tsan_warnings.txt
+
+The above exitcode makes TSan continue without error if any warnings are found.
+This allows for running the test and then checking the warnings afterwards.
+If you want TSan to stop and exit with error on warnings, use exitcode=66.
+
 VM testing
 ==========