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 4b29e59356e0044d82a69b7dba71bbbf512a9d2c..9bf2f34bafd063e4485c0ee7aa21e89d6e07f09d 100644 (file)
--- 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 0bbad48626328f212322d1b1acecb4be1dbf1b57..ada6910fa031c52f9a93925cf862840e48bfa52c 100644 (file)
--- 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 (file)
index 0000000..3f5121e
--- /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 a8e8e759ecf2ac061fb45543301f489de210bf41..20e5155cf4293bafc6eac4adaee458097565f9a5 100644 (file)
--- 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 1ccac87b73260ba8d81f0d2d45536d03327f8342..502cc5ceb2c60ddb6c0b0c8052f9377ee3884dd9 100644 (file)
--- 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
 -------------