From: Zhihong Peng <zhihongx.peng@intel.com>
Date: Wed, 20 Oct 2021 07:46:40 +0000 (+0800)
Subject: build: enable AddressSanitizer
X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=6e0290250d5cfa19a3cdb5e6a30634ddd317c85d;p=dpdk.git

build: enable AddressSanitizer

AddressSanitizer [1] a.k.a. ASan is a widely-used debugging tool to
detect memory access errors.
It helps to detect issues like use-after-free, various kinds of buffer
overruns in C/C++ programs, and other similar errors, as well as
printing out detailed debug information whenever an error is detected.

ASan is integrated with gcc and clang and can be enabled via a meson
option: -Db_sanitize=address
See the documentation for details (especially regarding clang).

Enabling ASan has an impact on performance since additional checks are
added to generated binaries.

Enabling ASan with Windows is currently not supported in DPDK.

1: https://github.com/google/sanitizers/wiki/AddressSanitizer

Signed-off-by: Xueqin Lin <xueqin.lin@intel.com>
Signed-off-by: Zhihong Peng <zhihongx.peng@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
---

diff --git a/config/meson.build b/config/meson.build
index 4b29e59356..9bf2f34baf 100644
--- a/config/meson.build
+++ b/config/meson.build
@@ -413,6 +413,22 @@ if get_option('b_lto')
     endif
 endif
 
+if get_option('b_sanitize') == 'address' or get_option('b_sanitize') == 'address,undefined'
+    if is_windows
+        error('ASan is not supported on windows')
+    endif
+
+    if cc.get_id() == 'gcc'
+        asan_dep = cc.find_library('asan', required: true)
+        if (not cc.links('int main(int argc, char *argv[]) { return 0; }',
+                dependencies: asan_dep))
+            error('broken dependency, "libasan"')
+        endif
+        add_project_link_arguments('-lasan', language: 'c')
+        dpdk_extra_ldflags += '-lasan'
+    endif
+endif
+
 if get_option('default_library') == 'both'
     error( '''
  Unsupported value "both" for "default_library" option.
diff --git a/devtools/words-case.txt b/devtools/words-case.txt
index 0bbad48626..ada6910fa0 100644
--- a/devtools/words-case.txt
+++ b/devtools/words-case.txt
@@ -5,6 +5,7 @@ API
 Arm
 armv7
 armv8
+ASan
 BAR
 CRC
 DCB
diff --git a/doc/guides/prog_guide/asan.rst b/doc/guides/prog_guide/asan.rst
new file mode 100644
index 0000000000..3f5121eabd
--- /dev/null
+++ b/doc/guides/prog_guide/asan.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+   Copyright(c) 2021 Intel Corporation
+
+Running AddressSanitizer
+========================
+
+`AddressSanitizer
+<https://github.com/google/sanitizers/wiki/AddressSanitizer>`_ (ASan)
+is a widely-used debugging tool to detect memory access errors.
+It helps to detect issues like use-after-free, various kinds of buffer
+overruns in C/C++ programs, and other similar errors, as well as
+printing out detailed debug information whenever an error is detected.
+
+AddressSanitizer is a part of LLVM (3.1+) and GCC (4.8+).
+
+Enabling ASan is done by passing the -Db_sanitize=address option to the meson build system,
+see :ref:`linux_gsg_compiling_dpdk` for details.
+
+The way ASan is integrated with clang requires to allow undefined symbols when linking code.
+To do this, the -Db_lundef=false option must be added.
+
+Additionally, passing -Dbuildtype=debug option might help getting more readable ASan reports.
+
+Example::
+
+  - gcc: meson setup -Db_sanitize=address <build_dir>
+  - clang: meson setup -Db_sanitize=address -Db_lundef=false <build_dir>
+
+.. Note::
+
+  - The libasan package must be installed when compiling with gcc in Centos/RHEL.
+  - If the program is tested using cmdline, you may need to execute the
+    "stty echo" command when an error occurs.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index a8e8e759ec..20e5155cf4 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -72,4 +72,5 @@ Programmer's Guide
     writing_efficient_code
     lto
     profile_app
+    asan
     glossary
diff --git a/doc/guides/rel_notes/release_21_11.rst b/doc/guides/rel_notes/release_21_11.rst
index 1ccac87b73..502cc5ceb2 100644
--- a/doc/guides/rel_notes/release_21_11.rst
+++ b/doc/guides/rel_notes/release_21_11.rst
@@ -305,6 +305,15 @@ New Features
     * Pcapng format with timestamps and meta-data.
     * Fixes packet capture with stripped VLAN tags.
 
+* **Added ASan support.**
+
+  `AddressSanitizer
+  <https://github.com/google/sanitizers/wiki/AddressSanitizer>`_ (ASan)
+  is a widely-used debugging tool to detect memory access errors.
+  It helps to detect issues like use-after-free, various kinds of buffer
+  overruns in C/C++ programs, and other similar errors, as well as
+  printing out detailed debug information whenever an error is detected.
+
 
 Removed Items
 -------------