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>

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.

devtools/words-case.txt

@@ -5,6 +5,7 @@ API
 Arm
 armv7
 armv8
+ASan
 BAR
 CRC
 DCB

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.

doc/guides/prog_guide/index.rst

@@ -72,4 +72,5 @@ Programmer's Guide
     writing_efficient_code
     lto
     profile_app
+    asan
     glossary

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
 -------------