Get location info from function indexes in addr2line script (#3206)

Update the `addr2line` script so that:
- line info is printed in a more convenient format, e.g.
```
0: c
        at wasm-micro-runtime/test-tools/addr2line/trap.c:5:1
1: b
        at wasm-micro-runtime/test-tools/addr2line/trap.c:11:12
2: a
        at wasm-micro-runtime/test-tools/addr2line/trap.c:17:12
```
similar to how Rust prints stack traces when there's a panic. In an IDE, the user
can conveniently click on the printed path and be redirected to the file line.
- a new `--no-addr` argument can be provided to the script 

It can be used in fast interpreter mode (that is not supported by the script otherwise)
or with older wamr versions (where the stack trace only had the function index info
and not the function address). In that case, `wasm-objdump` is used to get the function
name from the index and `llvm-dwarfdump` to obtain the location info (where the line
refers to the start of the function).

.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;
+}