From 87e64c929fa534ebd29b18f38fc6c15fd216e7e4 Mon Sep 17 00:00:00 2001
From: Benoît Ganne <bganne@cisco.com>
Date: Fri, 29 Nov 2019 17:28:30 +0100
Subject: docs: add AddressSanitizer mini-howto
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Type: docs

Change-Id: I3bb589d04f15a03166a6d457552ffc316fb02f94
Signed-off-by: Benoît Ganne <bganne@cisco.com>
---
 docs/troubleshooting/index.rst     |  1 +
 docs/troubleshooting/sanitizer.rst | 46 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 docs/troubleshooting/sanitizer.rst

(limited to 'docs')

diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst
index 655eb1192e6..f652f3f2184 100644
--- a/docs/troubleshooting/index.rst
+++ b/docs/troubleshooting/index.rst
@@ -11,3 +11,4 @@ problem with FD.io VPP implementations.
 
     reportingissues/index.rst
     cpuusage
+    sanitizer
diff --git a/docs/troubleshooting/sanitizer.rst b/docs/troubleshooting/sanitizer.rst
new file mode 100644
index 00000000000..af239943da3
--- /dev/null
+++ b/docs/troubleshooting/sanitizer.rst
@@ -0,0 +1,46 @@
+.. _sanitizer:
+
+**************
+Google Sanitizers
+**************
+
+VPP is instrumented to support `Google Sanitizers <https://github.com/google/sanitizers>`_.
+As of today, only `AddressSanitizer <https://github.com/google/sanitizers/wiki/AddressSanitizer>`_
+is supported and only for the heap.
+
+AddressSanitizer
+==============
+
+`AddressSanitizer <https://github.com/google/sanitizers/wiki/AddressSanitizer>`_  (aka ASan) is a memory
+error detector for C/C++. Think Valgrind but much faster.
+
+In order to use it, VPP must be recompiled with ASan support. It is implemented as a cmake
+build option, so all VPP targets should be supported. For example:
+
+.. code-block:: console
+
+    # build a debug image with ASan support:
+    $ make rebuild VPP_EXTRA_CMAKE_ARGS=-DENABLE_SANITIZE_ADDR=ON
+    ....
+
+    # build a release image with ASan support:
+    $ make rebuild-release VPP_EXTRA_CMAKE_ARGS=-DENABLE_SANITIZE_ADDR=ON
+    ....
+
+    # build packages in debug mode with ASan support:
+    $ make pkg-deb-debug VPP_EXTRA_CMAKE_ARGS=-DENABLE_SANITIZE_ADDR=ON
+    ....
+
+    # run GBP plugin tests in debug mode with ASan
+    $ make test-debug TEST=test_gbp VPP_EXTRA_CMAKE_ARGS=-DENABLE_SANITIZE_ADDR=ON
+    ....
+
+Once VPP has been built with ASan support, you can use it as usual. When
+running under a debugger it can be useful to disable LeakSanitizer which is
+not compatible with a debugger and displays spurious warnings at exit:
+
+.. code-block:: console
+
+    $ ASAN_OPTIONS=detect_leaks=0 gdb --args $PWD/build-root/install-vpp_debug-native/vpp/bin/vpp "unix { interactive }"
+    ....
+
-- 
cgit 1.2.3-korg