From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 1D963A034F;
Fri, 8 Oct 2021 11:38:49 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 8614C410DA;
Fri, 8 Oct 2021 11:38:45 +0200 (CEST)
Received: from mga17.intel.com (mga17.intel.com [192.55.52.151])
by mails.dpdk.org (Postfix) with ESMTP id 7F8E240685
for <dev@dpdk.org>; Fri, 8 Oct 2021 11:38:42 +0200 (CEST)
X-IronPort-AV: E=McAfee;i="6200,9189,10130"; a="207281866"
X-IronPort-AV: E=Sophos;i="5.85,357,1624345200"; d="scan'208";a="207281866"
Received: from orsmga008.jf.intel.com ([10.7.209.65])
by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
08 Oct 2021 02:28:18 -0700
X-IronPort-AV: E=Sophos;i="5.85,357,1624345200"; d="scan'208";a="489392431"
Received: from unknown (HELO localhost.localdomain) ([10.240.183.65])
by orsmga008-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
08 Oct 2021 02:28:15 -0700
From: zhihongx.peng@intel.com
To: anatoly.burakov@intel.com, konstantin.ananyev@intel.com,
stephen@networkplumber.org, david.marchand@redhat.com
Cc: dev@dpdk.org, xueqin.lin@intel.com, Zhihong Peng <zhihongx.peng@intel.com>
Date: Fri, 8 Oct 2021 09:17:49 +0000
Message-Id: <20211008091751.417468-1-zhihongx.peng@intel.com>
X-Mailer: git-send-email 2.25.1
In-Reply-To: <20210930125938.266731-1-zhihongx.peng@intel.com>
References: <20210930125938.266731-1-zhihongx.peng@intel.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: [dpdk-dev] [PATCH v7 1/3] Enable ASan for memory detector on DPDK
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>
From: Zhihong Peng <zhihongx.peng@intel.com>
AddressSanitizer (ASan) is a google memory error detect
standard tool. It could help to detect use-after-free and
{heap,stack,global}-buffer overflow bugs in C/C++ programs,
print detailed error information when error happens, large
improve debug efficiency.
`AddressSanitizer
<https://github.com/google/sanitizers/wiki/AddressSanitizer>` (ASan)
is a widely-used debugging tool to detect memory access errors.
It helps 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.
DPDK ASan functionality is currently only supported Linux x86_64.
Support other platforms, need to define ASAN_SHADOW_OFFSET value
according to google ASan document.
Here is an example of heap-buffer-overflow bug:
......
char *p = rte_zmalloc(NULL, 7, 0);
p[7] = 'a';
......
Here is an example of use-after-free bug:
......
char *p = rte_zmalloc(NULL, 7, 0);
rte_free(p);
*p = 'a';
......
We can enable ASan by adding below compilation options:
-Dbuildtype=debug -Db_lundef=false -Db_sanitize=address
"-Dbuildtype=debug": This is a non-essential option. When this option
is added, if a memory error occurs, ASan can clearly show where the
code is wrong.
"-Db_lundef=false": When use clang to compile DPDK, this option must
be added.
Signed-off-by: Xueqin Lin <xueqin.lin@intel.com>
Signed-off-by: Zhihong Peng <zhihongx.peng@intel.com>
---
devtools/words-case.txt | 1 +
doc/guides/prog_guide/asan.rst | 100 ++++++++++++++++++++++++++++++++
doc/guides/prog_guide/index.rst | 1 +
3 files changed, 102 insertions(+)
create mode 100644 doc/guides/prog_guide/asan.rst
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..fb48b9f10b
--- /dev/null
+++ b/doc/guides/prog_guide/asan.rst
@@ -0,0 +1,100 @@
+.. Copyright (c) <2021>, Intel Corporation
+ All rights reserved.
+
+Memory error detect standard tool - AddressSanitizer(ASan)
+==========================================================
+
+AddressSanitizer (ASan) is a google memory error detect
+standard tool. It could help to detect use-after-free and
+{heap,stack,global}-buffer overflow bugs in C/C++ programs,
+print detailed error information when error happens, large
+improve debug efficiency.
+
+By referring to its implementation algorithm
+(https://github.com/google/sanitizers/wiki/AddressSanitizerAlgorithm),
+enabled heap-buffer-overflow and use-after-free functions on DPDK.
+DPDK ASan function currently only supports on Linux x86_64.
+
+AddressSanitizer is a part of LLVM (3.1+) and GCC (4.8+).
+
+DPDK ASan functionality is currently only supported Linux x86_64.
+Support other platforms, need to define ASAN_SHADOW_OFFSET value
+according to google ASan document.
+
+Example heap-buffer-overflow error
+----------------------------------
+
+Following error was reported when ASan was enabled::
+
+ Applied 9 bytes of memory, but accessed the 10th byte of memory,
+ so heap-buffer-overflow appeared.
+
+Below code results in this error::
+
+ Add code to helloworld:
+ char *p = rte_zmalloc(NULL, 9, 0);
+ if (!p) {
+ printf("rte_zmalloc error.");
+ return -1;
+ }
+ p[9] = 'a';
+
+The error log::
+
+ ==369953==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x7fb17f465809 at pc 0x5652e6707b84 bp 0x7ffea70eea20 sp 0x7ffea70eea10 WRITE of size 1 at 0x7fb17f465809 thread T0
+ #0 0x5652e6707b83 in main ../examples/helloworld/main.c:47
+ #1 0x7fb94953c0b2 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x270b2)
+ #2 0x5652e67079bd in _start (/home/pzh/asan_test/x86_64-native-linuxapp-gcc/examples/dpdk-helloworld+0x8329bd)
+
+ Address 0x7fb17f465809 is a wild pointer.
+ SUMMARY: AddressSanitizer: heap-buffer-overflow ../examples/helloworld/main.c:47 in main
+
+Example use-after-free error
+----------------------------
+
+Following error was reported when ASan was enabled::
+
+ Applied for 9 bytes of memory, and accessed the first byte after
+ released, so heap-use-after-free appeared.
+
+Below code results in this error::
+
+ Add code to helloworld:
+ char *p = rte_zmalloc(NULL, 9, 0);
+ if (!p) {
+ printf("rte_zmalloc error.");
+ return -1;
+ }
+ rte_free(p);
+ *p = 'a';
+
+The error log::
+
+ ==417048==ERROR: AddressSanitizer: heap-use-after-free on address 0x7fc83f465800 at pc 0x564308a39b89 bp 0x7ffc8c85bf50 sp 0x7ffc8c85bf40 WRITE of size 1 at 0x7fc83f465800 thread T0
+ #0 0x564308a39b88 in main ../examples/helloworld/main.c:48
+ #1 0x7fd0079c60b2 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x270b2)
+ #2 0x564308a399bd in _start (/home/pzh/asan_test/x86_64-native-linuxapp-gcc/examples/dpdk-helloworld+0x8329bd)
+
+ Address 0x7fc83f465800 is a wild pointer.
+ SUMMARY: AddressSanitizer: heap-use-after-free ../examples/helloworld/main.c:48 in main
+
+Usage
+-----
+
+meson build
+^^^^^^^^^^^
+
+To enable ASan in meson build system, use following meson build command:
+
+Example usage::
+
+ meson build -Dbuildtype=debug -Db_lundef=false -Db_sanitize=address
+ ninja -C build
+
+.. Note::
+
+ a) Some of the features of ASan (for example, 'Display memory application location, currently
+ displayed as a wild pointer') are not currently supported by DPDK's implementation.
+ b) DPDK test has been completed in ubuntu18.04/ubuntu20.04/redhat8.3. Centos needs to install
+ libasan separately.
+ c) If the program uses cmdline, when a memory bug occurs, need to execute the "stty echo" command.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index 2dce507f46..df8a4b93e1 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -71,3 +71,4 @@ Programmer's Guide
lto
profile_app
glossary
+ asan
--
2.25.1