Add imported functions callback samples

.github/workflows/compilation_on_android_ubuntu.yml

@@ -622,6 +622,14 @@ jobs:
           ./shared_heap_test
           ./shared_heap_test --aot
 
+      - name: Build Sample [import-func-callback]
+        run: |
+          cd samples/import-func-callback
+          mkdir build && cd build
+          cmake ..
+          cmake --build . --config Release --parallel 4
+          ./import-func-callback
+
   test:
     needs:
       [

.github/workflows/compilation_on_macos.yml

@@ -422,3 +422,11 @@ jobs:
           cmake --build . --config Debug --parallel 4
           ./shared_heap_test
           ./shared_heap_test --aot
+
+      - name: Build Sample [import-func-callback]
+        run: |
+          cd samples/import-func-callback
+          mkdir build && cd build
+          cmake ..
+          cmake --build . --config Release --parallel 4
+          ./import-func-callback

.github/workflows/nightly_run.yml

@@ -568,6 +568,14 @@ jobs:
           ./shared_heap_test
           ./shared_heap_test --aot
 
+      - name: Build Sample [import-func-callback]
+        run: |
+          cd samples/import-func-callback
+          mkdir build && cd build
+          cmake ..
+          cmake --build . --config Release --parallel 4
+          ./import-func-callback
+
   test:
     needs: [build_iwasm, build_llvm_libraries_on_ubuntu, build_wamrc]
     runs-on: ${{ matrix.os }}

core/iwasm/include/wasm_export.h

@@ -1526,6 +1526,14 @@ wasm_runtime_get_native_addr_range(wasm_module_inst_t module_inst,
 /**
  * Get the number of import items for a WASM module
  *
+ * Typical usage scenario:
+ * Combine this function with wasm_runtime_get_import_count() to traverse
+ * all import items in a module. Use import_type.kind to filter and identify
+ * different types of import items.
+ *
+ * Example usage (as wasm_runtime_for_each_import_func() in
+ * samples/import-func-callback)
+ *
  * @param module the WASM module
  *
  * @return the number of imports (zero for none), or -1 for failure
@@ -1536,6 +1544,14 @@ wasm_runtime_get_import_count(const wasm_module_t module);
 /**
  * Get information about a specific WASM module import
  *
+ * Typical usage scenario:
+ * Combine this function with wasm_runtime_get_import_count() to traverse
+ * all import items in a module. Use import_type.kind to filter and identify
+ * different types of import items.
+ *
+ * Example usage (as wasm_runtime_for_each_import_func() in
+ * samples/import-func-callback)
+ *
  * @param module the WASM module
  * @param import_index the desired import index
  * @param import_type the location to store information about the import

samples/import-func-callback/CMakeLists.txt

@@ -0,0 +1,106 @@
+# Copyright (C) 2019 Intel Corporation.  All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+cmake_minimum_required (VERSION 3.14)
+
+include(CheckPIESupported)
+include(ExternalProject)
+
+project (import-func-callback)
+
+set (CMAKE_CXX_STANDARD 17)
+
+################  runtime settings  ################
+string (TOLOWER ${CMAKE_HOST_SYSTEM_NAME} WAMR_BUILD_PLATFORM)
+if (APPLE)
+  add_definitions(-DBH_PLATFORM_DARWIN)
+endif ()
+
+# Reset default 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 Debug)
+endif ()
+
+set (WAMR_BUILD_INTERP 1)
+
+if (NOT MSVC)
+  # linker 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")
+  if (WAMR_BUILD_TARGET MATCHES "X86_.*" OR WAMR_BUILD_TARGET STREQUAL "AMD_64")
+    if (NOT (CMAKE_C_COMPILER MATCHES ".*clang.*" OR CMAKE_C_COMPILER_ID MATCHES ".*Clang"))
+      set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mindirect-branch-register")
+    endif ()
+  endif ()
+endif ()
+
+# 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 ################
+if (NOT DEFINED WASI_SDK_DIR)
+    set (WASI_SDK_DIR "/opt/wasi-sdk")
+endif ()
+
+ExternalProject_Add(wasm_app
+    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/wasm-apps
+    BINARY_DIR ${CMAKE_CURRENT_BINARY_DIR}/wasm-apps
+    CONFIGURE_COMMAND ""
+    BUILD_COMMAND ${CMAKE_COMMAND} -E env
+        ${WASI_SDK_DIR}/bin/clang
+        -nostdlib
+        --target=wasm32
+        -Wl,--no-entry
+        -Wl,--export=test
+        -Wl,--allow-undefined
+        -o ${CMAKE_CURRENT_BINARY_DIR}/wasm-apps/test.wasm
+        ${CMAKE_CURRENT_SOURCE_DIR}/wasm-apps/test.c
+    BUILD_ALWAYS TRUE
+    INSTALL_COMMAND ""
+)
+
+################  application related  ################
+include_directories(${CMAKE_CURRENT_LIST_DIR}/src)
+include (${SHARED_DIR}/utils/uncommon/shared_uncommon.cmake)
+
+add_executable (import-func-callback src/main.c ${UNCOMMON_SHARED_SOURCE})
+
+add_dependencies(import-func-callback wasm_app)
+
+check_pie_supported()
+set_target_properties (import-func-callback PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+if (APPLE)
+  target_link_libraries (import-func-callback vmlib -lm -ldl -lpthread ${LLVM_AVAILABLE_LIBS})
+else ()
+  target_link_libraries (import-func-callback vmlib -lm -ldl -lpthread -lrt ${LLVM_AVAILABLE_LIBS})
+endif ()

samples/import-func-callback/README.md

@@ -0,0 +1,14 @@
+# "import function callback" sample introduction
+
+This sample demonstrates how to use import function callbacks to handle WebAssembly modules that import external functions. The sample shows how to register callback functions for imported functions and execute them when the WASM module loads these imported functions.
+
+The sample includes a WASM module that imports external functions and a host application that provides callback `import_func_type_callback` for these imported functions.
+
+## Build and run the sample
+
+```bash
+mkdir build && cd build
+cmake ..
+cmake --build . --config Release
+./import-func-callback
+```

samples/import-func-callback/src/main.c

@@ -0,0 +1,97 @@
+/*
+ * Copyright (C) 2019 Intel Corporation.  All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ */
+
+#include "wasm_export.h"
+#include "bh_read_file.h"
+#include "bh_getopt.h"
+#include "assert.h"
+
+typedef void (*wasm_func_type_callback_t)(const wasm_import_t *import_type);
+
+const char *import_func_names[] = { "import_func1", "import_func2" };
+
+void
+import_func_type_callback(const wasm_import_t *import_type)
+{
+    int ret = 0;
+    for (uint32_t i = 0;
+         i < sizeof(import_func_names) / sizeof(import_func_names[0]); i++) {
+        if (strcmp(import_type->name, import_func_names[i]) == 0) {
+            ret = 1;
+            break;
+        }
+    }
+    assert(ret == 1);
+    return;
+}
+
+/* Iterate over all import functions in the module */
+void
+wasm_runtime_for_each_import_func(const wasm_module_t module,
+                                  wasm_func_type_callback_t callback)
+{
+    int32_t import_count = wasm_runtime_get_import_count(module);
+    if (import_count <= 0)
+        return;
+    if (callback == NULL)
+        return;
+
+    for (int32_t i = 0; i < import_count; ++i) {
+        wasm_import_t import_type;
+        wasm_runtime_get_import_type(module, i, &import_type);
+
+        if (import_type.kind != WASM_IMPORT_EXPORT_KIND_FUNC) {
+            continue;
+        }
+
+        callback(&import_type);
+    }
+}
+
+int
+main(int argc, char *argv_main[])
+{
+    static char global_heap_buf[512 * 1024];
+    wasm_module_t module = NULL;
+    uint32 buf_size;
+    char *buffer = NULL;
+    const char *wasm_path = "wasm-apps/test.wasm";
+    char error_buf[128];
+
+    RuntimeInitArgs init_args;
+    memset(&init_args, 0, sizeof(RuntimeInitArgs));
+
+    init_args.mem_alloc_type = Alloc_With_Pool;
+    init_args.mem_alloc_option.pool.heap_buf = global_heap_buf;
+    init_args.mem_alloc_option.pool.heap_size = sizeof(global_heap_buf);
+
+    if (!wasm_runtime_full_init(&init_args)) {
+        printf("Init runtime environment failed.\n");
+        return -1;
+    }
+    buffer = bh_read_file_to_buffer(wasm_path, &buf_size);
+
+    if (!buffer) {
+        printf("Open wasm app file [%s] failed.\n", wasm_path);
+        goto fail;
+    }
+
+    module = wasm_runtime_load((uint8 *)buffer, buf_size, error_buf,
+                               sizeof(error_buf));
+    if (!module) {
+        printf("Load wasm app file [%s] failed.\n", wasm_path);
+        goto fail;
+    }
+
+    wasm_runtime_for_each_import_func(module, import_func_type_callback);
+
+fail:
+    if (module)
+        wasm_runtime_unload(module);
+    if (buffer)
+        BH_FREE(buffer);
+    wasm_runtime_destroy();
+    return 0;
+}

samples/import-func-callback/wasm-apps/test.c

@@ -0,0 +1,17 @@
+/*
+ * Copyright (C) 2019 Intel Corporation.  All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ */
+
+extern int
+import_func1(int a, int b);
+extern int
+import_func2(int a);
+
+int
+test()
+{
+    int a = import_func1(1, 2);
+    int b = import_func2(3);
+    return a + b;
+}