This includes details on how to build and test with TSan both inside a docker and outside.
Signed-off-by: Robert Foley <robert.fo...@linaro.org> --- docs/devel/testing.rst | 72 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) 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 ========== -- 2.17.1