test(addr2line): add stack trace symbolication to CI

.github/workflows/compilation_on_android_ubuntu.yml

@@ -448,6 +448,16 @@ jobs:
           ./build.sh
           ./run.sh
 
+      - name: Build Sample [debug-tools]
+        run: |
+          cd samples/debug-tools
+          mkdir build && cd build
+          cmake ..
+          cmake --build . --config Debug --parallel 4
+          ./iwasm wasm-apps/trap.wasm | grep "#" > call_stack.txt
+          ./iwasm wasm-apps/trap.aot | grep "#" > call_stack_aot.txt
+          bash -x ../symbolicate.sh         
+
   test:
     needs:
       [

.github/workflows/compilation_on_macos.yml

@@ -369,3 +369,13 @@ jobs:
           cd samples/terminate
           ./build.sh
           ./run.sh
+
+      - name: Build Sample [debug-tools]
+        run: |
+          cd samples/debug-tools
+          mkdir build && cd build
+          cmake ..
+          cmake --build . --config Debug --parallel 4
+          ./iwasm wasm-apps/trap.wasm | grep "#" > call_stack.txt
+          ./iwasm wasm-apps/trap.aot | grep "#" > call_stack_aot.txt
+          bash -x ../symbolicate.sh  

samples/README.md

@@ -1,5 +1,5 @@
-
 # Samples
+
 - [**basic**](./basic): Demonstrating how to use runtime exposed API's to call WASM functions, how to register native functions and call them, and how to call WASM function from native function.
 - **[file](./file/README.md)**: Demonstrating the supported file interaction API of WASI. This sample can also demonstrate the SGX IPFS (Intel Protected File System), enabling an enclave to seal and unseal data at rest.
 - **[multi-thread](./multi-thread/)**: Demonstrating how to run wasm application which creates multiple threads to execute wasm functions concurrently, and uses mutex/cond by calling pthread related API's.
@@ -12,3 +12,4 @@
 - **[native-lib](./native-lib/README.md)**: Demonstrating how to write required interfaces in native library, build it into a shared library and register the shared library to iwasm.
 - **[sgx-ra](./sgx-ra/README.md)**: Demonstrating how to execute Remote Attestation on SGX with [librats](https://github.com/inclavare-containers/librats), which enables mutual attestation with other runtimes or other entities that support librats to ensure that each is running within the TEE.
 - **[workload](./workload/README.md)**: Demonstrating how to build and run some complex workloads, e.g. tensorflow-lite, XNNPACK, wasm-av1, meshoptimizer and bwa.
+- **[debug-tools](./debug-tools/README.md)**: Demonstrating how to symbolicate a stack trace.

samples/debug-tools/CMakeLists.txt

@@ -0,0 +1,76 @@
+# Copyright (C) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+cmake_minimum_required(VERSION 3.14)
+
+include(CheckPIESupported)
+
+project(debug_tools_sample)
+
+################  runtime settings  ################
+string (TOLOWER ${CMAKE_HOST_SYSTEM_NAME} WAMR_BUILD_PLATFORM)
+if (APPLE)
+  add_definitions(-DBH_PLATFORM_DARWIN)
+endif ()
+
+# Resetdefault linker flags
+set(CMAKE_SHARED_LIBRARY_LINK_C_FLAGS "")
+set(CMAKE_SHARED_LIBRARY_LINK_CXX_FLAGS "")
+
+# WAMR features switch
+
+# Set WAMR_BUILD_TARGET, currently values supported:
+# "X86_64", "AMD_64", "X86_32", "AARCH64[sub]", "ARM[sub]", "THUMB[sub]",
+# "MIPS", "XTENSA", "RISCV64[sub]", "RISCV32[sub]"
+if (NOT DEFINED WAMR_BUILD_TARGET)
+  if (CMAKE_SYSTEM_PROCESSOR MATCHES "^(arm64|aarch64)")
+    set (WAMR_BUILD_TARGET "AARCH64")
+  elseif (CMAKE_SYSTEM_PROCESSOR STREQUAL "riscv64")
+    set (WAMR_BUILD_TARGET "RISCV64")
+  elseif (CMAKE_SIZEOF_VOID_P EQUAL 8)
+    # Build as X86_64 by default in 64-bit platform
+    set (WAMR_BUILD_TARGET "X86_64")
+  elseif (CMAKE_SIZEOF_VOID_P EQUAL 4)
+    # Build as X86_32 by default in 32-bit platform
+    set (WAMR_BUILD_TARGET "X86_32")
+  else ()
+    message(SEND_ERROR "Unsupported build target platform!")
+  endif ()
+endif ()
+
+if (NOT CMAKE_BUILD_TYPE)
+  set (CMAKE_BUILD_TYPE Release)
+endif ()
+
+set(WAMR_BUILD_INTERP 1)
+set(WAMR_BUILD_LIBC_WASI 1)
+set(WAMR_BUILD_FAST_INTERP 0)  # Otherwise addresses don't match llvm-dwarfdump (addr2line)
+set(WAMR_BUILD_AOT 1)
+set(WAMR_BUILD_DUMP_CALL_STACK 1) # Otherwise stack trace is not printed (addr2line)
+
+# compiling and linking flags
+if (NOT (CMAKE_C_COMPILER MATCHES ".*clang.*" OR CMAKE_C_COMPILER_ID MATCHES ".*Clang"))
+  set (CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,--gc-sections")
+endif ()
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall -Wextra -Wformat -Wformat-security")
+
+# build out vmlib
+set(WAMR_ROOT_DIR ${CMAKE_CURRENT_LIST_DIR}/../..)
+include (${WAMR_ROOT_DIR}/build-scripts/runtime_lib.cmake)
+
+add_library(vmlib ${WAMR_RUNTIME_LIB_SOURCE})
+
+################ wasm application ################
+add_subdirectory(wasm-apps)
+
+################ wamr runtime ################
+include (${SHARED_DIR}/utils/uncommon/shared_uncommon.cmake)
+
+set (RUNTIME_SOURCE_ALL
+    ${CMAKE_CURRENT_LIST_DIR}/../../product-mini/platforms/linux/main.c
+    ${UNCOMMON_SHARED_SOURCE}
+)
+add_executable (iwasm ${RUNTIME_SOURCE_ALL})
+check_pie_supported()
+set_target_properties (iwasm PROPERTIES POSITION_INDEPENDENT_CODE ON)
+target_link_libraries(iwasm vmlib -lm -ldl)

samples/debug-tools/README.md

@@ -0,0 +1,81 @@
+# "debug-tools" sample introduction
+
+Tool to symoblicate stack traces. When using wasm in production, debug info are usually stripped using tools like `wasm-opt`, to decrease the binary size. If a corresponding unstripped wasm file is kept, location information (function, file, line, column) can be retrieved from the stripped stack trace.
+
+## Build and run the sample
+
+### Generate the stack trace
+
+Build `iwasm` with `WAMR_BUILD_DUMP_CALL_STACK=1` and `WAMR_BUILD_FAST_INTERP=0` and the wasm file with debug info (e.g. `clang -g`). As it is done in [CMakeLists.txt](./CMakeLists.txt) and [wasm-apps/CMakeLists.txt](./wasm-apps/CMakeLists.txt) (look for `addr2line`):
+
+```bash
+$ mkdir build && cd build
+$ cmake ..
+$ make
+$ ./iwasm wasm-apps/trap.wasm
+```
+
+The output should be something like
+
+```text
+#00: 0x0159 - $f5
+#01: 0x01b2 - $f6
+#02: 0x0200 - $f7
+#03: 0x026b - $f8
+#04: 0x236b - $f15
+#05: 0x011f - _start
+
+Exception: unreachable
+```
+
+Copy the stack trace printed to stdout into a separate file (`call_stack.txt`):
+
+```bash
+$ ./iwasm wasm-apps/trap.wasm | grep "#" > call_stack.txt
+```
+
+Same for AOT. The AOT binary has to be generated using the `--enable-dump-call-stack` option of `wamrc`, as in [CMakeLists.txt](./wasm-apps/CMakeLists.txt). Then run:
+
+```bash
+$ ./iwasm wasm-apps/trap.aot | grep "#" > call_stack.txt
+```
+
+### Symbolicate the stack trace
+
+Run the [addr2line](../../test-tools/addr2line/addr2line.py) script to symbolicate the stack trace:
+
+```bash
+$ python3 ../../../test-tools/addr2line/addr2line.py \
+    --wasi-sdk /opt/wasi-sdk \
+    --wabt /opt/wabt \
+    --wasm-file wasm-apps/trap.wasm \
+    call_stack.txt
+```
+
+The output should be something like:
+
+```text
+0: c
+        at wasm-micro-runtime/samples/debug-tools/wasm-apps/trap.c:5:1
+1: b
+        at wasm-micro-runtime/samples/debug-tools/wasm-apps/trap.c:11:12
+2: a
+        at wasm-micro-runtime/samples/debug-tools/wasm-apps/trap.c:17:12
+3: main
+        at wasm-micro-runtime/samples/debug-tools/wasm-apps/trap.c:24:5
+4: <unknown>
+        at unknown:?:?
+5: _start
+```
+
+If WAMR is run in fast interpreter mode (`WAMR_BUILD_FAST_INTERP=1`), addresses in the stack trace cannot be tracked back to location info.
+If WAMR <= `1.3.2` is used, the stack trace does not contain addresses.
+In those two cases, run the script with `--no-addr`: the line info returned refers to the start of the function
+
+```bash
+$ python3 ../../../test-tools/addr2line/addr2line.py \
+    --wasi-sdk /opt/wasi-sdk \
+    --wabt /opt/wabt \
+    --wasm-file wasm-apps/trap.wasm \
+    call_stack.txt --no-addr
+```

samples/debug-tools/symbolicate.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -euox pipefail
+
+# Symbolicate .wasm
+python3 ../../../test-tools/addr2line/addr2line.py \
+    --wasi-sdk /opt/wasi-sdk \
+    --wabt /opt/wabt \
+    --wasm-file wasm-apps/trap.wasm \
+    call_stack.txt
+
+# Symbolicate .wasm with `--no-addr`
+python3 ../../../test-tools/addr2line/addr2line.py \
+    --wasi-sdk /opt/wasi-sdk \
+    --wabt /opt/wabt \
+    --wasm-file wasm-apps/trap.wasm \
+    call_stack.txt --no-addr
+
+# Symbolicate .aot
+python3 ../../../test-tools/addr2line/addr2line.py \
+    --wasi-sdk /opt/wasi-sdk \
+    --wabt /opt/wabt \
+    --wasm-file wasm-apps/trap.wasm \
+    call_stack_aot.txt

samples/debug-tools/wasm-apps/CMakeLists.txt

@@ -0,0 +1,91 @@
+# Copyright (C) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+if (APPLE)
+    set (HAVE_FLAG_SEARCH_PATHS_FIRST 0)
+    set (CMAKE_C_LINK_FLAGS "")
+    set (CMAKE_CXX_LINK_FLAGS "")
+endif ()
+
+if (NOT DEFINED WASI_SDK_DIR)
+  set (WASI_SDK_DIR               "/opt/wasi-sdk")
+endif ()
+
+if (DEFINED WASI_SYSROOT)
+  set (CMAKE_SYSROOT                "${WASI_SYSROOT}")
+endif ()
+
+set (CMAKE_C_COMPILER               "${WASI_SDK_DIR}/bin/clang")
+set (CMAKE_ASM_COMPILER               "${WASI_SDK_DIR}/bin/clang")
+set (CMAKE_EXE_LINKER_FLAGS         "-target wasm32-wasi")
+
+################ wabt and wamrc dependencies ################
+message(CHECK_START "Detecting WABT")
+if(NOT (DEFINED WABT_DIR OR DEFINED CACHE{WABT_DIR}))
+  find_path(WABT_DIR
+    wabt
+    PATHS /opt
+    NO_DEFAULT_PATH
+    NO_CMAKE_FIND_ROOT_PATH
+  )
+  if(DEFINED WABT_DIR)
+    set(WABT_DIR ${WABT_DIR}/wabt)
+  endif()
+endif()
+if(WABT_DIR)
+  message(CHECK_PASS "found")
+else()
+  message(CHECK_FAIL "not found")
+endif()
+
+message(CHECK_START "Detecting WASM_OBJDUMP at ${WABT_DIR}")
+find_program(WASM_OBJDUMP
+  wasm-objdump
+  PATHS "${WABT_DIR}/bin"
+  NO_DEFAULT_PATH
+  NO_CMAKE_FIND_ROOT_PATH
+)
+if(WASM_OBJDUMP)
+  message(CHECK_PASS "found")
+else()
+  message(CHECK_FAIL "not found")
+endif()
+if((NOT EXISTS ${WASM_OBJDUMP}) )
+  message(FATAL_ERROR "Please make sure to have wasm-objdump under the path=${WABT_DIR}/bin ")
+endif()
+
+set(WAMR_COMPILER_DIR ${CMAKE_CURRENT_LIST_DIR}/../../wamr-compiler/build)
+message(CHECK_START "Detecting WAMR_COMPILER at ${WAMR_COMPILER_DIR}")
+find_file(WAMR_COMPILER
+  wamrc
+  PATHS "${CMAKE_CURRENT_LIST_DIR}/../../../wamr-compiler/build"
+  NO_DEFAULT_PATH
+  NO_CMAKE_FIND_ROOT_PATH
+)
+if(WAMR_COMPILER)
+  message(CHECK_PASS "found")
+else()
+  message(CHECK_FAIL "not found")
+endif()
+if((NOT EXISTS ${WAMR_COMPILER}) )
+  message(FATAL_ERROR "Please build wamrc under the path=${WAMR_ROOT_DIR}/wamr-compiler/")
+endif()
+
+################ wasm and aot compilation ################
+function (compile_sample SOURCE_FILE)
+  get_filename_component (FILE_NAME ${SOURCE_FILE} NAME_WLE)
+  set (WASM_MODULE ${FILE_NAME}.wasm)
+  add_executable (${WASM_MODULE} ${SOURCE_FILE})
+
+  add_custom_target(
+    wasm_to_aot
+    ALL
+    DEPENDS ${WAMR_COMPILER} ${WASM_MODULE}
+    # Use --enable-dump-call-stack to generate stack trace (addr2line)
+    COMMAND ${WAMR_COMPILER} --size-level=0 --enable-dump-call-stack -o wasm-apps/trap.aot wasm-apps/trap.wasm
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  )
+endfunction ()
+
+set(CMAKE_BUILD_TYPE Debug)  # Otherwise no debug symbols (addr2line)
+compile_sample(trap.c)

samples/debug-tools/wasm-apps/trap.c

@@ -0,0 +1,27 @@
+int
+c(int n)
+{
+    __builtin_trap();
+}
+
+int
+b(int n)
+{
+    n += 3;
+    return c(n);
+}
+
+int
+a(int n)
+{
+    return b(n);
+}
+
+int
+main(int argc, char **argv)
+{
+    int i = 5;
+    a(i);
+
+    return 0;
+}

test-tools/addr2line/addr2line.py

@@ -293,14 +293,4 @@ def main():
 
 
 if __name__ == "__main__":
-    print(
-        "**************************************************\n"
-        + "Before running this script, please make sure:\n"
-        + "  - the wasm file is compiled with debug info, like: clang -g\n"
-        + "  - the call-stack dump is generated by iwasm\n"
-        + "  - iwasm is compiled with -DWAMR_BUILD_DUMP_CALL_STACK=1\n"
-        + "  - this script is run with `--no-addr` if iwasm is running in fast-interp mode (-DWAMR_BUILD_FAST_INTERP=1)\n"
-        + "  - if using .aot, the aot file is generated with `--enable-dump-call-stack`\n"
-        + "**************************************************\n"
-    )
     sys.exit(main())