Iterate callstack API

Author: Georgii Rylov

core/iwasm/aot/aot_runtime.c

@@ -10,6 +10,7 @@
 #include "../common/wasm_runtime_common.h"
 #include "../common/wasm_memory.h"
 #include "../interpreter/wasm_runtime.h"
+#include <stdbool.h>
 #if WASM_ENABLE_SHARED_MEMORY != 0
 #include "../common/wasm_shared_memory.h"
 #endif
@@ -4104,6 +4105,48 @@ aot_frame_update_profile_info(WASMExecEnv *exec_env, bool alloc_frame)
 #endif /* end of WASM_ENABLE_AOT_STACK_FRAME != 0 */
 
 #if WASM_ENABLE_DUMP_CALL_STACK != 0
+void 
+aot_iterate_callstack(WASMExecEnv *exec_env, const wasm_frame_callback frame_handler, void* user_data)
+{
+/*
+* Note for devs: please refrain from such modifications inside of aot_iterate_callstack
+ * - any allocations/freeing memory
+ * - dereferencing any pointers other than: exec_env, exec_env->module_inst,
+ * exec_env->module_inst->module, pointers between stack's bottom and top_boundary
+ * For more details check wasm_iterate_callstack in wasm_export.h
+*/
+    if (!is_tiny_frame(exec_env)) {
+        //TODO: support standard frames
+        return;
+    }
+    uint8* top_boundary = exec_env->wasm_stack.top_boundary;
+    uint8* top = exec_env->wasm_stack.top;
+    uint8* bottom = exec_env->wasm_stack.bottom;
+
+    bool is_top_index_in_range = top_boundary >= top && top >= (bottom + sizeof(AOTTinyFrame));
+    if (!is_top_index_in_range) {
+        return;
+    }
+    bool is_top_aligned_with_bottom = (unsigned long)(top - bottom) % sizeof(AOTTinyFrame) == 0;
+    if (!is_top_aligned_with_bottom) {
+        return;
+    }
+
+    AOTTinyFrame* frame = (AOTTinyFrame*)(top - sizeof(AOTTinyFrame));
+    WASMCApiFrame record_frame;
+    while (frame && 
+        (uint8_t*)frame >= bottom) {
+        record_frame.instance = exec_env->module_inst;
+        record_frame.module_offset = 0;
+        record_frame.func_index = frame->func_index;
+        record_frame.func_offset = frame->ip_offset;
+        if (!frame_handler(user_data, &record_frame)) {
+            break;
+        }
+        frame -= 1;
+    }
+}
+
 bool
 aot_create_call_stack(struct WASMExecEnv *exec_env)
 {

core/iwasm/aot/aot_runtime.h

@@ -777,6 +777,9 @@ aot_frame_update_profile_info(WASMExecEnv *exec_env, bool alloc_frame);
 bool
 aot_create_call_stack(struct WASMExecEnv *exec_env);
 
+void 
+aot_iterate_callstack(WASMExecEnv *exec_env, const wasm_frame_callback frame_handler, void* user_data);
+
 /**
  * @brief Dump wasm call stack or get the size
  *

core/iwasm/common/wasm_runtime_common.c

@@ -7,6 +7,7 @@
 #include "bh_common.h"
 #include "bh_assert.h"
 #include "bh_log.h"
+#include "wasm_export.h"
 #include "wasm_native.h"
 #include "wasm_runtime_common.h"
 #include "wasm_memory.h"
@@ -1740,6 +1741,33 @@ wasm_runtime_destroy_exec_env(WASMExecEnv *exec_env)
     wasm_exec_env_destroy(exec_env);
 }
 
+void 
+wasm_iterate_callstack(const wasm_exec_env_t exec_env, const wasm_frame_callback frame_callback, void* user_data)
+{
+/*
+* Note for devs: please refrain from such modifications inside of wasm_iterate_callstack
+ * - any allocations/freeing memory
+ * - dereferencing any pointers other than: exec_env, exec_env->module_inst,
+ * exec_env->module_inst->module, pointers between stack's bottom and top_boundary
+ * For more details check wasm_iterate_callstack in wasm_export.h
+*/
+    #if WASM_ENABLE_DUMP_CALL_STACK
+    WASMModuleInstance* module_inst = (WASMModuleInstance *)get_module_inst(exec_env);
+
+    #if WASM_ENABLE_INTERP != 0
+    if (module_inst->module_type == Wasm_Module_Bytecode) {
+        wasm_interp_iterate_callstack(exec_env, frame_callback, user_data);
+    }
+    #endif
+
+    #if WASM_ENABLE_AOT != 0
+    if (module_inst->module_type == Wasm_Module_AoT) {
+        aot_iterate_callstack(exec_env, frame_callback, user_data);
+    }
+    #endif
+    #endif
+}
+
 bool
 wasm_runtime_init_thread_env(void)
 {

core/iwasm/common/wasm_runtime_common.h

@@ -652,6 +652,9 @@ wasm_runtime_create_exec_env(WASMModuleInstanceCommon *module_inst,
 WASM_RUNTIME_API_EXTERN void
 wasm_runtime_destroy_exec_env(WASMExecEnv *exec_env);
 
+WASM_RUNTIME_API_EXTERN void 
+wasm_iterate_callstack(const wasm_exec_env_t exec_env, const wasm_frame_callback frame_handler, void* user_data);
+
 /* See wasm_export.h for description */
 WASM_RUNTIME_API_EXTERN WASMModuleInstanceCommon *
 wasm_runtime_get_module_inst(WASMExecEnv *exec_env);

core/iwasm/include/wasm_export.h

@@ -126,6 +126,9 @@ typedef WASMFunctionInstanceCommon *wasm_function_inst_t;
 struct WASMMemoryInstance;
 typedef struct WASMMemoryInstance *wasm_memory_inst_t;
 
+struct wasm_frame_t;
+typedef struct wasm_frame_t * wasm_frame_ptr_t;
+
 /* WASM section */
 typedef struct wasm_section_t {
     struct wasm_section_t *next;
@@ -864,6 +867,37 @@ wasm_runtime_create_exec_env(wasm_module_inst_t module_inst,
 WASM_RUNTIME_API_EXTERN void
 wasm_runtime_destroy_exec_env(wasm_exec_env_t exec_env);
 
+
+typedef bool (*wasm_frame_callback)(void*, wasm_frame_ptr_t);
+
+/**
+ * @brief Iterate over callstack frames and execute callback on it.
+ *
+ * Caution: This is not a thread-safe function. Ensure the exec_env 
+ * is suspended before calling it from another thread.
+ *
+ * Usage: In the callback to read frames fields use APIs 
+ * for wasm_frame_t from wasm_c_api.h
+ *
+ * Note: The function is async-signal-safe if called with verified arguments. 
+ * Meaning it's safe to call it from a signal handler even on a signal interruption
+ * from another thread if next variables hold valid pointers
+ * - exec_env
+ * - exec_env->module_inst
+ * - exec_env->module_inst->module
+ *
+ * Note for devs: please refrain from such modifications inside of this call
+ * - any allocations/freeing memory
+ * - dereferencing any pointers other than: exec_env, exec_env->module_inst,
+ * exec_env->module_inst->module, pointers between stack's bottom and top_boundary
+ *
+ * @param exec_env the execution environment that containes frames
+ * @param callback the callback function provided by the user
+ * @param user_data context for callback provided by the user
+ */
+WASM_RUNTIME_API_EXTERN void 
+wasm_iterate_callstack(const wasm_exec_env_t exec_env, const wasm_frame_callback callback, void *user_data);
+
 /**
  * Get the singleton execution environment for the instance.
  *

core/iwasm/interpreter/wasm_interp.h

@@ -26,6 +26,8 @@ typedef struct WASMInterpFrame {
     /* Instruction pointer of the bytecode array.  */
     uint8 *ip;
 
+    uint32 func_index;
+
 #if WASM_ENABLE_FAST_JIT != 0
     uint8 *jitted_return_addr;
 #endif

core/iwasm/interpreter/wasm_interp_classic.c

@@ -1264,9 +1264,11 @@ wasm_interp_call_func_native(WASMModuleInstance *module_inst,
     init_frame_refs(frame_ref, local_cell_num, cur_func);
 #endif
 
+    cur_func_index = (uint32)(cur_func - module_inst->e->functions);
+    frame->func_index = cur_func_index;
+
     wasm_exec_env_set_cur_frame(exec_env, frame);
 
-    cur_func_index = (uint32)(cur_func - module_inst->e->functions);
     bh_assert(cur_func_index < module_inst->module->import_function_count);
     if (!func_import->call_conv_wasm_c_api) {
         native_func_pointer = module_inst->import_func_ptrs[cur_func_index];

core/iwasm/interpreter/wasm_interp_fast.c

@@ -1205,9 +1205,11 @@ wasm_interp_call_func_native(WASMModuleInstance *module_inst,
     init_frame_refs(frame->frame_ref, local_cell_num, cur_func);
 #endif
 
+    cur_func_index = (uint32)(cur_func - module_inst->e->functions);
+    frame->func_index = cur_func_index;
+
     wasm_exec_env_set_cur_frame(exec_env, frame);
 
-    cur_func_index = (uint32)(cur_func - module_inst->e->functions);
     bh_assert(cur_func_index < module_inst->module->import_function_count);
     if (!func_import->call_conv_wasm_c_api) {
         native_func_pointer = module_inst->import_func_ptrs[cur_func_index];
@@ -6032,6 +6034,7 @@ wasm_interp_call_func_bytecode(WASMModuleInstance *module,
 
             /* Initialize the interpreter context. */
             frame->function = cur_func;
+            frame->func_index = (uint32)(cur_func - module->e->functions);
             frame_ip = wasm_get_func_code(cur_func);
             frame_ip_end = wasm_get_func_code_end(cur_func);
 

core/iwasm/interpreter/wasm_runtime.c

@@ -5,6 +5,7 @@
 
 #include "wasm_runtime.h"
 #include "wasm.h"
+#include "wasm_exec_env.h"
 #include "wasm_loader.h"
 #include "wasm_interp.h"
 #include "bh_common.h"
@@ -4196,6 +4197,35 @@ wasm_get_module_inst_mem_consumption(const WASMModuleInstance *module_inst,
                  || (WASM_ENABLE_MEMORY_TRACING != 0) */
 
 #if WASM_ENABLE_DUMP_CALL_STACK != 0
+uint32 
+wasm_interp_iterate_callstack(WASMExecEnv *exec_env, const wasm_frame_callback frame_handler, void* user_data)
+{
+/*
+* Note for devs: please refrain from such modifications inside of wasm_interp_iterate_callstack
+ * - any allocations/freeing memory
+ * - dereferencing any pointers other than: exec_env, exec_env->module_inst,
+ * exec_env->module_inst->module, pointers between stack's bottom and top_boundary
+ * For more details check wasm_iterate_callstack in wasm_export.h
+*/
+    WASMModuleInstance *module_inst = (WASMModuleInstance *)wasm_exec_env_get_module_inst(exec_env);
+    WASMInterpFrame* cur_frame = wasm_exec_env_get_cur_frame(exec_env);
+    uint8* top_boundary = exec_env->wasm_stack.top_boundary;
+    uint8* bottom = exec_env->wasm_stack.bottom;
+
+    WASMCApiFrame record_frame;
+    while (cur_frame &&
+        (uint8_t*)cur_frame >= bottom &&
+        (uint8_t*)cur_frame + sizeof(WASMInterpFrame) <= top_boundary) {
+            record_frame.instance = module_inst;
+            record_frame.module_offset = 0;
+            record_frame.func_index = cur_frame->func_index;
+            if (!frame_handler(user_data, &record_frame)) {
+                break;
+            }
+            cur_frame = cur_frame->prev_frame;
+    }
+}
+
 bool
 wasm_interp_create_call_stack(struct WASMExecEnv *exec_env)
 {

core/iwasm/interpreter/wasm_runtime.h

@@ -730,6 +730,10 @@ wasm_get_table_inst(const WASMModuleInstance *module_inst, uint32 tbl_idx)
 }
 
 #if WASM_ENABLE_DUMP_CALL_STACK != 0
+
+uint32 
+wasm_interp_iterate_callstack(WASMExecEnv *exec_env, const wasm_frame_callback frame_handler, void* user_data);
+
 bool
 wasm_interp_create_call_stack(struct WASMExecEnv *exec_env);