From patchwork Tue Jun 16 12:53:18 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Alex_Benn=C3=A9e?= X-Patchwork-Id: 188036 Delivered-To: patch@linaro.org Received: by 2002:a92:cf06:0:0:0:0:0 with SMTP id c6csp3630143ilo; Tue, 16 Jun 2020 06:04:15 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxvvZaC+mkMVxnc+I/kEAdlkHylRsPG8k3JdX/j9mlg44H/KasxmVP1GsSRyuUIoAmmY38U X-Received: by 2002:aed:2ca5:: with SMTP id g34mr21706124qtd.13.1592312655666; Tue, 16 Jun 2020 06:04:15 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1592312655; cv=none; d=google.com; s=arc-20160816; b=htkVDE3u4e12XGZhxG4w/lUS82xo713i6vEE9FAP5yL+it3E7S7YK/d6iSBLnFxY5S qjyKHxLxMOaFBQIlrQJ8FC9HUBykytjXGGSApebynmb2tSHRBLIPO86C00pDsgEPao1Q EGADCjOiLi90T8zconwmmGwjDlHypSP95S3RjDEYvlYCIPfbTCQ/TPVPV3yWik4LJU+6 UEuZ/yLjy6ROOJX5gN01D6ZOuQgEZ3WRsOFMspNMyoEJK3XX6DVoKCICE/SI1MHlRyfD rtjABqndbq8eO/eCRdrtQqNgvzvCdj34FxJWZEzjmL9LqplEJMLu88ur/e2PN8LncxNX XCcQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:to:from :dkim-signature; bh=1xJcLKKf4A1w+f4XuWFSl147HgeADv1qlqWle+NmUxo=; b=i7L2wSb2NXSR1Cqcwbx8exeX9+EiEI+6H/IviuHlioEq5a/7SECQDHCDFi2q03jSx1 HtC74twP1Uc5PrwtIJoVuGBQPaANYK8xp8YMAs1OzMsBB1TZ/aVFWsJJte8VvVSzCy2A /ZI3OCgamYfvE2/kkEK9XxlpA5LkklMue3qhQK0fk+scsRn8Fd1dSzC5C2TX1yrG7M5Z u58WX8Dxy0rZlmyPDEHC9o2LKqxaCr7xpElAa/sTYNaVy/IMSBM/xZIyouq+NyY2GBeI n92YYiInY5q0PNIRiS8sthfe0xeRgfvkSl1XUJ4LkBIlkmlHYJObbk0jU9xmyqMc8dnR 9AYA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=sJtqT0pu; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id p6si10391347qta.119.2020.06.16.06.04.15 for (version=TLS1_2 cipher=ECDHE-ECDSA-CHACHA20-POLY1305 bits=256/256); Tue, 16 Jun 2020 06:04:15 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=sJtqT0pu; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([::1]:42192 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jlBGB-0002a4-0l for patch@linaro.org; Tue, 16 Jun 2020 09:04:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:36420) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jlBDc-00083b-4G for qemu-devel@nongnu.org; Tue, 16 Jun 2020 09:01:36 -0400 Received: from mail-wm1-x32a.google.com ([2a00:1450:4864:20::32a]:51694) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jlBDa-0001bl-3E for qemu-devel@nongnu.org; Tue, 16 Jun 2020 09:01:35 -0400 Received: by mail-wm1-x32a.google.com with SMTP id b82so2809156wmb.1 for ; Tue, 16 Jun 2020 06:01:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=1xJcLKKf4A1w+f4XuWFSl147HgeADv1qlqWle+NmUxo=; b=sJtqT0puhEWoszXMqX9aeptZkemZ8XLl/+Cx29hrq4TqhIcJVLNe7pKkqfJNpAb7yB 1SE/uJtLHueCJfCdOdgyupGVaIYdazyk3Uvyjm1sJzzkSa9kvXvGfvz4JwlVjSZkugZ6 S2AEjqwzPD6imJv5ondgxKenQWAGm5vV0WJw0uYv/zfKX/MkaHzyhLtKP8UK6H7yh3GE 6sofrLMR9t1PM2j3gQ3+u2r4Vizb+u7UDL9i7QjLuYWxYDWNogzC8hiUNEBSG6yGZJYf qdy66BjrXbIIWuac7tAegNfnL39qKHmAh9APRMHLVcH0Jqudu9tI0J0SNYuv9T3LOF0Y onuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=1xJcLKKf4A1w+f4XuWFSl147HgeADv1qlqWle+NmUxo=; b=N2rXNzP4RK22ZGY41tdyn94MGQEBovZsRDYngo2SfnBYurV3u97WCZSepVlDLWtBEq LPSWMCC7d+iH0coMArefrBwNJBOEvk8POdCwRa4A9JdtVB9Rkq+NfN0zWPFRwyAs/xWg bFEAkE9cU4F/RmIxRVCbcXjOh22h5DoNdbfR719CqDpg7uM7aGvH4zd8mdaDijY63ZnY jOY8VFqTmYRic5Xw6Y2iKSDE15g5LohXdxikNNvAob+uTF3pig9LK2tSiVN89vbEVVgM cgPAfG/Jq1TSxU4y8VXMIxskILW3VVTJmwRekvZPWViguG67MGQMSIuhD0JkfUKRG3hA E5Ug== X-Gm-Message-State: AOAM531mu+ZAgLSsspjkF825AH747E9lAWdrus5ZVLAnoiqLoW5QR/v3 8FvA140VFKyq/E56oHPWv9TlKw== X-Received: by 2002:a1c:9613:: with SMTP id y19mr3035700wmd.135.1592312492438; Tue, 16 Jun 2020 06:01:32 -0700 (PDT) Received: from zen.linaroharston ([51.148.130.216]) by smtp.gmail.com with ESMTPSA id 185sm3870497wmz.22.2020.06.16.06.01.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Jun 2020 06:01:29 -0700 (PDT) Received: from zen.lan (localhost [127.0.0.1]) by zen.linaroharston (Postfix) with ESMTP id AF3A41FF9E; Tue, 16 Jun 2020 13:53:25 +0100 (BST) From: =?utf-8?q?Alex_Benn=C3=A9e?= To: peter.maydell@linaro.org Subject: [PULL 15/21] docs: Added details on TSan to testing.rst Date: Tue, 16 Jun 2020 13:53:18 +0100 Message-Id: <20200616125324.19045-16-alex.bennee@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200616125324.19045-1-alex.bennee@linaro.org> References: <20200616125324.19045-1-alex.bennee@linaro.org> MIME-Version: 1.0 Received-SPF: pass client-ip=2a00:1450:4864:20::32a; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x32a.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=_AUTOLEARN X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Emilio G . Cota" , =?utf-8?q?Alex_Benn=C3=A9e?= , qemu-devel@nongnu.org, Robert Foley Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" From: Robert Foley Adds TSan details to testing.rst. This includes background and reference details on TSan, and details on how to build and test with TSan both with and without docker. Signed-off-by: Robert Foley Reviewed-by: Emilio G. Cota Reviewed-by: Alex Bennée Signed-off-by: Alex Bennée Message-Id: <20200609200738.445-13-robert.foley@linaro.org> Message-Id: <20200612190237.30436-16-alex.bennee@linaro.org> -- 2.20.1 diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 770a987ea42..c1ff24370bf 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -397,6 +397,113 @@ 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 +================ + +Thread Sanitizer (TSan) is a tool which can detect data races. QEMU supports +building and testing with this tool. + +For more information on TSan: + +https://github.com/google/sanitizers/wiki/ThreadSanitizerCppManual + +Thread Sanitizer in Docker +--------------------------- +TSan is currently supported in the ubuntu2004 docker. + +The test-tsan test will build using TSan and then run make check. + +.. code:: + + make docker-test-tsan@ubuntu2004 + +TSan warnings under docker 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. + +Building and Testing with TSan +------------------------------ + +It is possible to build and test with TSan, with a few additional steps. +These steps are normally done automatically in the docker. + +There is a one time patch needed in clang-9 or clang-10 at this time: + +.. code:: + + sed -i 's/^const/static const/g' \ + /usr/lib/llvm-10/lib/clang/10.0.0/include/sanitizer/tsan_interface.h + +To configure the build for TSan: + +.. code:: + + ../configure --enable-tsan --cc=clang-10 --cxx=clang++-10 \ + --disable-werror --extra-cflags="-O0" + +The runtime behavior of TSAN is controlled by the TSAN_OPTIONS environment +variable. + +More information on the TSAN_OPTIONS can be found here: + +https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags + +For example: + +.. code:: + + export TSAN_OPTIONS=suppressions=/tests/tsan/suppressions.tsan \ + detect_deadlocks=false history_size=7 exitcode=0 \ + log_path=/tsan/tsan_warning + +The above exitcode=0 has 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. + +TSan Suppressions +----------------- +Keep in mind that for any data race warning, although there might be a data race +detected by TSan, there might be no actual bug here. TSan provides several +different mechanisms for suppressing warnings. In general it is recommended +to fix the code if possible to eliminate the data race rather than suppress +the warning. + +A few important files for suppressing warnings are: + +tests/tsan/suppressions.tsan - Has TSan warnings we wish to suppress at runtime. +The comment on each supression will typically indicate why we are +suppressing it. More information on the file format can be found here: + +https://github.com/google/sanitizers/wiki/ThreadSanitizerSuppressions + +tests/tsan/blacklist.tsan - Has TSan warnings we wish to disable +at compile time for test or debug. +Add flags to configure to enable: + +"--extra-cflags=-fsanitize-blacklist=/tests/tsan/blacklist.tsan" + +More information on the file format can be found here under "Blacklist Format": + +https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags + +TSan Annotations +---------------- +include/qemu/tsan.h defines annotations. See this file for more descriptions +of the annotations themselves. Annotations can be used to suppress +TSan warnings or give TSan more information so that it can detect proper +relationships between accesses of data. + +Annotation examples can be found here: + +https://github.com/llvm/llvm-project/tree/master/compiler-rt/test/tsan/ + +Good files to start with are: annotate_happens_before.cpp and ignore_race.cpp + +The full set of annotations can be found here: + +https://github.com/llvm/llvm-project/blob/master/compiler-rt/lib/tsan/rtl/tsan_interface_ann.cpp + VM testing ==========