doc/guides/prog_guide/asan.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright(c) 2021 Intel Corporation
   3
   4 Running AddressSanitizer
   5 ========================
   6
   7 `AddressSanitizer
   8 <https://github.com/google/sanitizers/wiki/AddressSanitizer>`_ (ASan)
   9 is a widely-used debugging tool to detect memory access errors.
  10 It helps to detect issues like use-after-free, various kinds of buffer
  11 overruns in C/C++ programs, and other similar errors, as well as
  12 printing out detailed debug information whenever an error is detected.
  13
  14 AddressSanitizer is a part of LLVM (3.1+) and GCC (4.8+).
  15
  16 Enabling ASan is done by passing the -Db_sanitize=address option to the meson build system,
  17 see :ref:`linux_gsg_compiling_dpdk` for details.
  18
  19 The way ASan is integrated with clang requires to allow undefined symbols when linking code.
  20 To do this, the -Db_lundef=false option must be added.
  21
  22 Additionally, passing -Dbuildtype=debug option might help getting more readable ASan reports.
  23
  24 Example::
  25
  26   - gcc: meson setup -Db_sanitize=address <build_dir>
  27   - clang: meson setup -Db_sanitize=address -Db_lundef=false <build_dir>
  28
  29 .. Note::
  30
  31   - The libasan package must be installed when compiling with gcc in Centos/RHEL.
  32   - If the program is tested using cmdline, you may need to execute the
  33     "stty echo" command when an error occurs.
  34
  35 ASan is aware of DPDK memory allocations, thanks to added instrumentation, and
  36 is enabled on all 64 bit architectures for Linux. Other architectures may have
  37 to define ASAN_SHADOW_OFFSET.
  38
  39 Example heap-buffer-overflow error
  40 ----------------------------------
  41
  42 Add below unit test code in examples/helloworld/main.c::
  43
  44     Add code to helloworld:
  45     char *p = rte_zmalloc(NULL, 9, 0);
  46     if (!p) {
  47         printf("rte_zmalloc error.\n");
  48         return -1;
  49     }
  50     p[9] = 'a';
  51
  52 Above code will result in heap-buffer-overflow error if ASan is enabled, because apply 9 bytes of memory but access the tenth byte, detailed error log as below::
  53
  54     ==369953==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x7fb17f465809 at pc 0x5652e6707b84 bp 0x7ffea70eea20 sp 0x7ffea70eea10 WRITE of size 1 at 0x7fb17f465809 thread T0
  55     #0 0x5652e6707b83 in main ../examples/helloworld/main.c:47
  56     #1 0x7fb94953c0b2 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x270b2)
  57     #2 0x5652e67079bd in _start (/home/pzh/asan_test/x86_64-native-linuxapp-gcc/examples/dpdk-helloworld+0x8329bd)
  58
  59     Address 0x7fb17f465809 is a wild pointer.
  60     SUMMARY: AddressSanitizer: heap-buffer-overflow ../examples/helloworld/main.c:47 in main
  61
  62 Note::
  63
  64   - Some of the features of ASan (for example, 'Display memory application location, currently
  65     displayed as a wild pointer') are not currently supported with DPDK allocations.
  66
  67 Example use-after-free error
  68 ----------------------------
  69
  70 Add below unit test code in examples/helloworld/main.c::
  71
  72     Add code to helloworld:
  73     char *p = rte_zmalloc(NULL, 9, 0);
  74     if (!p) {
  75         printf("rte_zmalloc error.\n");
  76         return -1;
  77     }
  78     rte_free(p);
  79     *p = 'a';
  80
  81 Above code will result in use-after-free error if ASan is enabled, because apply 9 bytes of memory but access the first byte after release, detailed error log as below::
  82
  83     ==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
  84     #0 0x564308a39b88 in main ../examples/helloworld/main.c:48
  85     #1 0x7fd0079c60b2 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x270b2)
  86     #2 0x564308a399bd in _start (/home/pzh/asan_test/x86_64-native-linuxapp-gcc/examples/dpdk-helloworld+0x8329bd)
  87
  88     Address 0x7fc83f465800 is a wild pointer.
  89     SUMMARY: AddressSanitizer: heap-use-after-free ../examples/helloworld/main.c:48 in main