/* * Copyright (C) 2019 Intel Corporation. All rights reserved. * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception */ /** * @file wasm_export.h * * @brief This file defines the exported common runtime APIs */ #ifndef _WASM_EXPORT_H #define _WASM_EXPORT_H #include #include #include "lib_export.h" #ifndef WASM_RUNTIME_API_EXTERN #if defined(_MSC_BUILD) #if defined(COMPILING_WASM_RUNTIME_API) #define WASM_RUNTIME_API_EXTERN __declspec(dllexport) #else #define WASM_RUNTIME_API_EXTERN __declspec(dllimport) #endif #else #define WASM_RUNTIME_API_EXTERN #endif #endif #ifdef __cplusplus extern "C" { #endif #define get_module_inst(exec_env) wasm_runtime_get_module_inst(exec_env) #define validate_app_addr(offset, size) \ wasm_runtime_validate_app_addr(module_inst, offset, size) #define validate_app_str_addr(offset) \ wasm_runtime_validate_app_str_addr(module_inst, offset) #define addr_app_to_native(offset) \ wasm_runtime_addr_app_to_native(module_inst, offset) #define addr_native_to_app(ptr) \ wasm_runtime_addr_native_to_app(module_inst, ptr) #define module_malloc(size, p_native_addr) \ wasm_runtime_module_malloc(module_inst, size, p_native_addr) #define module_free(offset) wasm_runtime_module_free(module_inst, offset) #define native_raw_return_type(type, args) type *raw_ret = (type *)(args) #define native_raw_get_arg(type, name, args) type name = *((type *)(args++)) #define native_raw_set_return(val) *raw_ret = (val) #ifndef WASM_MODULE_T_DEFINED #define WASM_MODULE_T_DEFINED /* Uninstantiated WASM module loaded from WASM binary file or AoT binary file*/ struct WASMModuleCommon; typedef struct WASMModuleCommon *wasm_module_t; #endif typedef enum { WASM_IMPORT_EXPORT_KIND_FUNC, WASM_IMPORT_EXPORT_KIND_TABLE, WASM_IMPORT_EXPORT_KIND_MEMORY, WASM_IMPORT_EXPORT_KIND_GLOBAL } wasm_import_export_kind_t; struct WASMFuncType; typedef struct WASMFuncType *wasm_func_type_t; struct WASMGlobalType; typedef struct WASMGlobalType *wasm_global_type_t; struct WASMMemory; typedef struct WASMMemory WASMMemoryType; typedef WASMMemoryType *wasm_memory_type_t; typedef struct wasm_import_t { const char *module_name; const char *name; wasm_import_export_kind_t kind; bool linked; union { wasm_func_type_t func_type; wasm_global_type_t global_type; wasm_memory_type_t memory_type; } u; } wasm_import_t; typedef struct wasm_export_t { const char *name; wasm_import_export_kind_t kind; union { wasm_func_type_t func_type; wasm_global_type_t global_type; wasm_memory_type_t memory_type; } u; } wasm_export_t; /* Instantiated WASM module */ struct WASMModuleInstanceCommon; typedef struct WASMModuleInstanceCommon *wasm_module_inst_t; /* Function instance */ typedef void WASMFunctionInstanceCommon; typedef WASMFunctionInstanceCommon *wasm_function_inst_t; /* WASM section */ typedef struct wasm_section_t { struct wasm_section_t *next; /* section type */ int section_type; /* section body, not include type and size */ uint8_t *section_body; /* section body size */ uint32_t section_body_size; } wasm_section_t, aot_section_t, *wasm_section_list_t, *aot_section_list_t; /* Execution environment, e.g. stack info */ struct WASMExecEnv; typedef struct WASMExecEnv *wasm_exec_env_t; /* Package Type */ typedef enum { Wasm_Module_Bytecode = 0, Wasm_Module_AoT, Package_Type_Unknown = 0xFFFF } package_type_t; #ifndef MEM_ALLOC_OPTION_DEFINED #define MEM_ALLOC_OPTION_DEFINED /* Memory allocator type */ typedef enum { /* pool mode, allocate memory from user defined heap buffer */ Alloc_With_Pool = 0, /* user allocator mode, allocate memory from user defined malloc function */ Alloc_With_Allocator, /* system allocator mode, allocate memory from system allocator, or, platform's os_malloc function */ Alloc_With_System_Allocator, } mem_alloc_type_t; typedef enum { Alloc_For_Runtime, Alloc_For_LinearMemory } mem_alloc_usage_t; /* Memory allocator option */ typedef union MemAllocOption { struct { void *heap_buf; uint32_t heap_size; } pool; struct { /* the function signature is varied when WASM_MEM_ALLOC_WITH_USER_DATA and WASM_MEM_ALLOC_WITH_USAGE are defined */ void *malloc_func; void *realloc_func; void *free_func; /* allocator user data, only used when WASM_MEM_ALLOC_WITH_USER_DATA is defined */ void *user_data; } allocator; } MemAllocOption; #endif /* Memory pool info */ typedef struct mem_alloc_info_t { uint32_t total_size; uint32_t total_free_size; uint32_t highmark_size; } mem_alloc_info_t; /* Running mode of runtime and module instance*/ typedef enum RunningMode { Mode_Interp = 1, Mode_Fast_JIT, Mode_LLVM_JIT, Mode_Multi_Tier_JIT, } RunningMode; /* WASM runtime initialize arguments */ typedef struct RuntimeInitArgs { mem_alloc_type_t mem_alloc_type; MemAllocOption mem_alloc_option; const char *native_module_name; NativeSymbol *native_symbols; uint32_t n_native_symbols; /* maximum thread number, only used when WASM_ENABLE_THREAD_MGR is defined */ uint32_t max_thread_num; /* Debug settings, only used when WASM_ENABLE_DEBUG_INTERP != 0 */ char ip_addr[128]; int unused; /* was platform_port */ int instance_port; /* Fast JIT code cache size */ uint32_t fast_jit_code_cache_size; /* Default GC heap size */ uint32_t gc_heap_size; /* Default running mode of the runtime */ RunningMode running_mode; /* LLVM JIT opt and size level */ uint32_t llvm_jit_opt_level; uint32_t llvm_jit_size_level; /* Segue optimization flags for LLVM JIT */ uint32_t segue_flags; /** * If enabled * - llvm-jit will output a jitdump file for `perf inject` * - aot will output a perf-${pid}.map for `perf record` * - fast-jit. TBD * - multi-tier-jit. TBD * - interpreter. TBD */ bool enable_linux_perf; } RuntimeInitArgs; #ifndef LOAD_ARGS_OPTION_DEFINED #define LOAD_ARGS_OPTION_DEFINED typedef struct LoadArgs { char *name; /* This option is only used by the Wasm C API (see wasm_c_api.h) */ bool clone_wasm_binary; /* False by default, used by AOT/wasm loader only. If true, the AOT/wasm loader creates a copy of some module fields (e.g. const strings), making it possible to free the wasm binary buffer after loading. */ bool wasm_binary_freeable; /* TODO: more fields? */ } LoadArgs; #endif /* LOAD_ARGS_OPTION_DEFINED */ #ifndef INSTANTIATION_ARGS_OPTION_DEFINED #define INSTANTIATION_ARGS_OPTION_DEFINED /* WASM module instantiation arguments */ typedef struct InstantiationArgs { uint32_t default_stack_size; uint32_t host_managed_heap_size; uint32_t max_memory_pages; } InstantiationArgs; #endif /* INSTANTIATION_ARGS_OPTION_DEFINED */ #ifndef WASM_VALKIND_T_DEFINED #define WASM_VALKIND_T_DEFINED typedef uint8_t wasm_valkind_t; enum wasm_valkind_enum { WASM_I32, WASM_I64, WASM_F32, WASM_F64, WASM_V128, WASM_EXTERNREF = 128, WASM_FUNCREF, }; #endif #ifndef WASM_VAL_T_DEFINED #define WASM_VAL_T_DEFINED struct wasm_ref_t; typedef struct wasm_val_t { wasm_valkind_t kind; uint8_t _paddings[7]; union { /* also represent a function index */ int32_t i32; int64_t i64; float f32; double f64; /* represent a foreign object, aka externref in .wat */ uintptr_t foreign; struct wasm_ref_t *ref; } of; } wasm_val_t; #endif /* Global instance*/ typedef struct wasm_global_inst_t { wasm_valkind_t kind; bool is_mutable; void *global_data; } wasm_global_inst_t; typedef enum { WASM_LOG_LEVEL_FATAL = 0, WASM_LOG_LEVEL_ERROR = 1, WASM_LOG_LEVEL_WARNING = 2, WASM_LOG_LEVEL_DEBUG = 3, WASM_LOG_LEVEL_VERBOSE = 4 } log_level_t; /** * Initialize the WASM runtime environment, and also initialize * the memory allocator with system allocator, which calls os_malloc * to allocate memory * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_init(void); /** * Initialize the WASM runtime environment, WASM running mode, * and also initialize the memory allocator and register native symbols, * which are specified with init arguments * * @param init_args specifies the init arguments * * @return return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_full_init(RuntimeInitArgs *init_args); /** * Set the log level. To be called after the runtime is initialized. * * @param level the log level to set */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_log_level(log_level_t level); /** * Query whether a certain running mode is supported for the runtime * * @param running_mode the running mode to query * * @return true if this running mode is supported, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_running_mode_supported(RunningMode running_mode); /** * Set the default running mode for the runtime. It is inherited * to set the running mode of a module instance when it is instantiated, * and can be changed by calling wasm_runtime_set_running_mode * * @param running_mode the running mode to set * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_set_default_running_mode(RunningMode running_mode); /** * Destroy the WASM runtime environment. */ WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy(void); /** * Allocate memory from runtime memory environment. * * @param size bytes need to allocate * * @return the pointer to memory allocated */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_malloc(unsigned int size); /** * Reallocate memory from runtime memory environment * * @param ptr the original memory * @param size bytes need to reallocate * * @return the pointer to memory reallocated */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_realloc(void *ptr, unsigned int size); /* * Free memory to runtime memory environment. */ WASM_RUNTIME_API_EXTERN void wasm_runtime_free(void *ptr); /* * Get memory info, only pool mode is supported now. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_get_mem_alloc_info(mem_alloc_info_t *mem_alloc_info); /** * Get the package type of a buffer. * * @param buf the package buffer * @param size the package buffer size * * @return the package type, return Package_Type_Unknown if the type is unknown */ WASM_RUNTIME_API_EXTERN package_type_t get_package_type(const uint8_t *buf, uint32_t size); /** * Check whether a file is an AOT XIP (Execution In Place) file * * @param buf the package buffer * @param size the package buffer size * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_xip_file(const uint8_t *buf, uint32_t size); /** * Callback to load a module file into a buffer in multi-module feature */ typedef bool (*module_reader)(package_type_t module_type, const char *module_name, uint8_t **p_buffer, uint32_t *p_size); /** * Callback to release the buffer loaded by module_reader callback */ typedef void (*module_destroyer)(uint8_t *buffer, uint32_t size); /** * Setup callbacks for reading and releasing a buffer about a module file * * @param reader a callback to read a module file into a buffer * @param destroyer a callback to release above buffer */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_module_reader(const module_reader reader, const module_destroyer destroyer); /** * Give the "module" a name "module_name". * Can not assign a new name to a module if it already has a name * * @param module_name indicate a name * @param module the target module * @param error_buf output of the exception info * @param error_buf_size the size of the exception string * * @return true means success, false means failed */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_register_module(const char *module_name, wasm_module_t module, char *error_buf, uint32_t error_buf_size); /** * Check if there is already a loaded module named module_name in the * runtime. Repeatedly loading a module with the same name is not allowed. * * @param module_name indicate a name * * @return return WASM module loaded, NULL if failed */ WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_find_module_registered(const char *module_name); /** * Load a WASM module from a specified byte buffer. The byte buffer can be * WASM binary data when interpreter or JIT is enabled, or AOT binary data * when AOT is enabled. If it is AOT binary data, it must be 4-byte aligned. * * Note: In case of AOT XIP modules, the runtime doesn't make modifications * to the buffer. (Except the "Known issues" mentioned in doc/xip.md.) * Otherwise, the runtime can make modifications to the buffer for its * internal purposes. Thus, in general, it isn't safe to create multiple * modules from a single buffer. * * @param buf the byte buffer which contains the WASM/AOT binary data, * note that the byte buffer must be writable since runtime may * change its content for footprint and performance purpose, and * it must be referenceable until wasm_runtime_unload is called * @param size the size of the buffer * @param error_buf output of the exception info * @param error_buf_size the size of the exception string * * @return return WASM module loaded, NULL if failed */ WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_load(uint8_t *buf, uint32_t size, char *error_buf, uint32_t error_buf_size); /** * Load a WASM module with specified load argument. */ WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_load_ex(uint8_t *buf, uint32_t size, const LoadArgs *args, char *error_buf, uint32_t error_buf_size); /** * Load a WASM module from a specified WASM or AOT section list. * * @param section_list the section list which contains each section data * @param is_aot whether the section list is AOT section list * @param error_buf output of the exception info * @param error_buf_size the size of the exception string * * @return return WASM module loaded, NULL if failed */ WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_load_from_sections(wasm_section_list_t section_list, bool is_aot, char *error_buf, uint32_t error_buf_size); /** * Unload a WASM module. * * @param module the module to be unloaded */ WASM_RUNTIME_API_EXTERN void wasm_runtime_unload(wasm_module_t module); /** * Get the module hash of a WASM module, currently only available on * linux-sgx platform when the remote attestation feature is enabled * * @param module the WASM module to retrieve * * @return the module hash of the WASM module */ char * wasm_runtime_get_module_hash(wasm_module_t module); /** * Set WASI parameters. * * While this API operates on a module, these parameters will be used * only when the module is instantiated. That is, you can consider these * as extra parameters for wasm_runtime_instantiate(). * * @param module The module to set WASI parameters. * @param dir_list The list of directories to preopen. (real path) * @param dir_count The number of elements in dir_list. * @param map_dir_list The list of directories to preopen. (mapped path) * Format for each map entry: :: * @param map_dir_count The number of elements in map_dir_list. * If map_dir_count is smaller than dir_count, * mapped path is assumed to be same as the * corresponding real path for the rest of entries. * @param env The list of environment variables. * @param env_count The number of elements in env. * @param argv The list of command line arguments. * @param argc The number of elements in argv. * @param stdin_handle The raw host handle to back WASI STDIN_FILENO. * If an invalid handle is specified (e.g. -1 on POSIX, * INVALID_HANDLE_VALUE on Windows), the platform default * for STDIN is used. * @param stdoutfd The raw host handle to back WASI STDOUT_FILENO. * If an invalid handle is specified (e.g. -1 on POSIX, * INVALID_HANDLE_VALUE on Windows), the platform default * for STDOUT is used. * @param stderrfd The raw host handle to back WASI STDERR_FILENO. * If an invalid handle is specified (e.g. -1 on POSIX, * INVALID_HANDLE_VALUE on Windows), the platform default * for STDERR is used. */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_wasi_args_ex(wasm_module_t module, const char *dir_list[], uint32_t dir_count, const char *map_dir_list[], uint32_t map_dir_count, const char *env[], uint32_t env_count, char *argv[], int argc, int64_t stdinfd, int64_t stdoutfd, int64_t stderrfd); /** * Set WASI parameters. * * Same as wasm_runtime_set_wasi_args_ex but with default stdio handles */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_wasi_args(wasm_module_t module, const char *dir_list[], uint32_t dir_count, const char *map_dir_list[], uint32_t map_dir_count, const char *env[], uint32_t env_count, char *argv[], int argc); WASM_RUNTIME_API_EXTERN void wasm_runtime_set_wasi_addr_pool(wasm_module_t module, const char *addr_pool[], uint32_t addr_pool_size); WASM_RUNTIME_API_EXTERN void wasm_runtime_set_wasi_ns_lookup_pool(wasm_module_t module, const char *ns_lookup_pool[], uint32_t ns_lookup_pool_size); /** * Instantiate a WASM module. * * @param module the WASM module to instantiate * @param default_stack_size the default stack size of the module instance when * the exec env's operation stack isn't created by user, e.g. API * wasm_application_execute_main() and wasm_application_execute_func() * create the operation stack internally with the stack size specified * here. And API wasm_runtime_create_exec_env() creates the operation * stack with stack size specified by its parameter, the stack size * specified here is ignored. * @param host_managed_heap_size the default heap size of the module instance, * a heap will be created besides the app memory space. Both wasm app * and native function can allocate memory from the heap. * @param error_buf buffer to output the error info if failed * @param error_buf_size the size of the error buffer * * @return return the instantiated WASM module instance, NULL if failed */ WASM_RUNTIME_API_EXTERN wasm_module_inst_t wasm_runtime_instantiate(const wasm_module_t module, uint32_t default_stack_size, uint32_t host_managed_heap_size, char *error_buf, uint32_t error_buf_size); /** * Instantiate a WASM module, with specified instantiation arguments * * Same as wasm_runtime_instantiate, but it also allows overwriting maximum * memory */ WASM_RUNTIME_API_EXTERN wasm_module_inst_t wasm_runtime_instantiate_ex(const wasm_module_t module, const InstantiationArgs *args, char *error_buf, uint32_t error_buf_size); /** * Set the running mode of a WASM module instance, override the * default running mode of the runtime. Note that it only makes sense when * the input is a wasm bytecode file: for the AOT file, runtime always runs * it with AOT engine, and this function always returns true. * * @param module_inst the WASM module instance to set running mode * @param running_mode the running mode to set * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_set_running_mode(wasm_module_inst_t module_inst, RunningMode running_mode); /** * Get the running mode of a WASM module instance, if no running mode * is explicitly set the default running mode of runtime will * be used and returned. Note that it only makes sense when the input is a * wasm bytecode file: for the AOT file, this function always returns 0. * * @param module_inst the WASM module instance to query for running mode * * @return the running mode this module instance currently use */ WASM_RUNTIME_API_EXTERN RunningMode wasm_runtime_get_running_mode(wasm_module_inst_t module_inst); /** * Deinstantiate a WASM module instance, destroy the resources. * * @param module_inst the WASM module instance to destroy */ WASM_RUNTIME_API_EXTERN void wasm_runtime_deinstantiate(wasm_module_inst_t module_inst); /** * Get WASM module from WASM module instance * * @param module_inst the WASM module instance to retrieve * * @return the WASM module */ WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_get_module(wasm_module_inst_t module_inst); WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_wasi_mode(wasm_module_inst_t module_inst); WASM_RUNTIME_API_EXTERN wasm_function_inst_t wasm_runtime_lookup_wasi_start_function(wasm_module_inst_t module_inst); /** * Get WASI exit code. * * After a WASI command completed its execution, an embedder can * call this function to get its exit code. (that is, the value given * to proc_exit.) * * @param module_inst the module instance */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_get_wasi_exit_code(wasm_module_inst_t module_inst); /** * Lookup an exported function in the WASM module instance. * * @param module_inst the module instance * @param name the name of the function * * @return the function instance found, NULL if not found */ WASM_RUNTIME_API_EXTERN wasm_function_inst_t wasm_runtime_lookup_function(wasm_module_inst_t const module_inst, const char *name); /** * Get parameter count of the function instance * * @param func_inst the function instance * @param module_inst the module instance the function instance belongs to * * @return the parameter count of the function instance */ WASM_RUNTIME_API_EXTERN uint32_t wasm_func_get_param_count(wasm_function_inst_t const func_inst, wasm_module_inst_t const module_inst); /** * Get result count of the function instance * * @param func_inst the function instance * @param module_inst the module instance the function instance belongs to * * @return the result count of the function instance */ WASM_RUNTIME_API_EXTERN uint32_t wasm_func_get_result_count(wasm_function_inst_t const func_inst, wasm_module_inst_t const module_inst); /** * Get parameter types of the function instance * * @param func_inst the function instance * @param module_inst the module instance the function instance belongs to * @param param_types the parameter types returned */ WASM_RUNTIME_API_EXTERN void wasm_func_get_param_types(wasm_function_inst_t const func_inst, wasm_module_inst_t const module_inst, wasm_valkind_t *param_types); /** * Get result types of the function instance * * @param func_inst the function instance * @param module_inst the module instance the function instance belongs to * @param result_types the result types returned */ WASM_RUNTIME_API_EXTERN void wasm_func_get_result_types(wasm_function_inst_t const func_inst, wasm_module_inst_t const module_inst, wasm_valkind_t *result_types); /** * Create execution environment for a WASM module instance. * * @param module_inst the module instance * @param stack_size the stack size to execute a WASM function * * @return the execution environment, NULL if failed, e.g. invalid * stack size is passed */ WASM_RUNTIME_API_EXTERN wasm_exec_env_t wasm_runtime_create_exec_env(wasm_module_inst_t module_inst, uint32_t stack_size); /** * Destroy the execution environment. * * @param exec_env the execution environment to destroy */ WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_exec_env(wasm_exec_env_t exec_env); /** * Get the singleton execution environment for the instance. * * Note: The singleton execution environment is the execution * environment used internally by the runtime for the API functions * like wasm_application_execute_main, which don't take explicit * execution environment. It's associated to the corresponding * module instance and managed by the runtime. The API user should * not destroy it with wasm_runtime_destroy_exec_env. * * @param module_inst the module instance * * @return exec_env the execution environment to destroy */ WASM_RUNTIME_API_EXTERN wasm_exec_env_t wasm_runtime_get_exec_env_singleton(wasm_module_inst_t module_inst); /** * Start debug instance based on given execution environment. * Note: * The debug instance will be destroyed during destroying the * execution environment, developers don't need to destroy it * manually. * If the cluster of this execution environment has already * been bound to a debug instance, this function will return true * directly. * If developer spawns some exec_env by wasm_runtime_spawn_exec_env, * don't need to call this function for every spawned exec_env as * they are sharing the same cluster with the main exec_env. * * @param exec_env the execution environment to start debug instance * @param port the port for the debug server to listen on. * 0 means automatic assignment. * -1 means to use the global setting in RuntimeInitArgs. * * @return debug port if success, 0 otherwise. */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_start_debug_instance_with_port(wasm_exec_env_t exec_env, int32_t port); /** * Same as wasm_runtime_start_debug_instance_with_port(env, -1). */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_start_debug_instance(wasm_exec_env_t exec_env); /** * Initialize the thread environment. * Note: * If developer creates a child thread by himself to call the * the wasm function in that thread, he should call this API * firstly before calling the wasm function and then call * wasm_runtime_destroy_thread_env() after calling the wasm * function. If the thread is created from the runtime API, * it is unnecessary to call these two APIs. * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_init_thread_env(void); /** * Destroy the thread environment */ WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_thread_env(void); /** * Whether the thread environment is initialized */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_thread_env_inited(void); /** * Get WASM module instance from execution environment * * @param exec_env the execution environment to retrieve * * @return the WASM module instance */ WASM_RUNTIME_API_EXTERN wasm_module_inst_t wasm_runtime_get_module_inst(wasm_exec_env_t exec_env); /** * Set WASM module instance of execution environment * Caution: * normally the module instance is bound with the execution * environment one by one, if multiple module instances want * to share to the same execution environment, developer should * be responsible for the backup and restore of module instance * * @param exec_env the execution environment * @param module_inst the WASM module instance to set */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_module_inst(wasm_exec_env_t exec_env, const wasm_module_inst_t module_inst); /** * Call the given WASM function of a WASM module instance with * arguments (bytecode and AoT). * * @param exec_env the execution environment to call the function, * which must be created from wasm_create_exec_env() * @param function the function to call * @param argc total cell number that the function parameters occupy, * a cell is a slot of the uint32 array argv[], e.g. i32/f32 argument * occupies one cell, i64/f64 argument occupies two cells, note that * it might be different from the parameter number of the function * @param argv the arguments. If the function has return value, * the first (or first two in case 64-bit return value) element of * argv stores the return value of the called WASM function after this * function returns. * * @return true if success, false otherwise and exception will be thrown, * the caller can call wasm_runtime_get_exception to get the exception * info. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_call_wasm(wasm_exec_env_t exec_env, wasm_function_inst_t function, uint32_t argc, uint32_t argv[]); /** * Call the given WASM function of a WASM module instance with * provided results space and arguments (bytecode and AoT). * * @param exec_env the execution environment to call the function, * which must be created from wasm_create_exec_env() * @param function the function to call * @param num_results the number of results * @param results the pre-alloced pointer to get the results * @param num_args the number of arguments * @param args the arguments * * @return true if success, false otherwise and exception will be thrown, * the caller can call wasm_runtime_get_exception to get the exception * info. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_call_wasm_a(wasm_exec_env_t exec_env, wasm_function_inst_t function, uint32_t num_results, wasm_val_t results[], uint32_t num_args, wasm_val_t *args); /** * Call the given WASM function of a WASM module instance with * provided results space and variant arguments (bytecode and AoT). * * @param exec_env the execution environment to call the function, * which must be created from wasm_create_exec_env() * @param function the function to call * @param num_results the number of results * @param results the pre-alloced pointer to get the results * @param num_args the number of arguments * @param ... the variant arguments * * @return true if success, false otherwise and exception will be thrown, * the caller can call wasm_runtime_get_exception to get the exception * info. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_call_wasm_v(wasm_exec_env_t exec_env, wasm_function_inst_t function, uint32_t num_results, wasm_val_t results[], uint32_t num_args, ...); /** * Call a function reference of a given WASM runtime instance with * arguments. * * Note: this can be used to call a function which is not exported * by the module explicitly. You might consider it as an abstraction * violation. * * @param exec_env the execution environment to call the function * which must be created from wasm_create_exec_env() * @param element_index the function reference index, usually * provided by the caller of a registered native function * @param argc the number of arguments * @param argv the arguments. If the function method has return value, * the first (or first two in case 64-bit return value) element of * argv stores the return value of the called WASM function after this * function returns. * * @return true if success, false otherwise and exception will be thrown, * the caller can call wasm_runtime_get_exception to get exception info. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_call_indirect(wasm_exec_env_t exec_env, uint32_t element_index, uint32_t argc, uint32_t argv[]); /** * Find the unique main function from a WASM module instance * and execute that function. * * @param module_inst the WASM module instance * @param argc the number of arguments * @param argv the arguments array, if the main function has return value, * *(int*)argv stores the return value of the called main function after * this function returns. * * @return true if the main function is called, false otherwise and exception * will be thrown, the caller can call wasm_runtime_get_exception to get * the exception info. */ WASM_RUNTIME_API_EXTERN bool wasm_application_execute_main(wasm_module_inst_t module_inst, int32_t argc, char *argv[]); /** * Find the specified function in argv[0] from a WASM module instance * and execute that function. * * @param module_inst the WASM module instance * @param name the name of the function to execute. * to indicate the module name via: $module_name$function_name * or just a function name: function_name * @param argc the number of arguments * @param argv the arguments array * * @return true if the specified function is called, false otherwise and * exception will be thrown, the caller can call wasm_runtime_get_exception * to get the exception info. */ WASM_RUNTIME_API_EXTERN bool wasm_application_execute_func(wasm_module_inst_t module_inst, const char *name, int32_t argc, char *argv[]); /** * Get exception info of the WASM module instance. * * @param module_inst the WASM module instance * * @return the exception string */ WASM_RUNTIME_API_EXTERN const char * wasm_runtime_get_exception(wasm_module_inst_t module_inst); /** * Set exception info of the WASM module instance. * * @param module_inst the WASM module instance * * @param exception the exception string */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_exception(wasm_module_inst_t module_inst, const char *exception); /** * Clear exception info of the WASM module instance. * * @param module_inst the WASM module instance */ WASM_RUNTIME_API_EXTERN void wasm_runtime_clear_exception(wasm_module_inst_t module_inst); /** * Terminate the WASM module instance. * * This function causes the module instance fail as if it raised a trap. * * This is intended to be used in situations like: * * - A thread is executing the WASM module instance * (eg. it's in the middle of `wasm_application_execute_main`) * * - Another thread has a copy of `wasm_module_inst_t` of * the module instance and wants to terminate it asynchronously. * * @param module_inst the WASM module instance */ WASM_RUNTIME_API_EXTERN void wasm_runtime_terminate(wasm_module_inst_t module_inst); /** * Set custom data to WASM module instance. * Note: * If WAMR_BUILD_LIB_PTHREAD is enabled, this API * will spread the custom data to all threads * * @param module_inst the WASM module instance * @param custom_data the custom data to be set */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_custom_data(wasm_module_inst_t module_inst, void *custom_data); /** * Get the custom data within a WASM module instance. * * @param module_inst the WASM module instance * * @return the custom data (NULL if not set yet) */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_get_custom_data(wasm_module_inst_t module_inst); /** * Set the memory bounds checks flag of a WASM module instance. * * @param module_inst the WASM module instance * @param enable the flag to enable/disable the memory bounds checks */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_bounds_checks(wasm_module_inst_t module_inst, bool enable); /** * Check if the memory bounds checks flag is enabled for a WASM module instance. * * @param module_inst the WASM module instance * @return true if the memory bounds checks flag is enabled, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_bounds_checks_enabled(wasm_module_inst_t module_inst); /** * Allocate memory from the heap of WASM module instance * * Note: wasm_runtime_module_malloc can call heap functions inside * the module instance and thus cause a memory growth. * This API needs to be used very carefully when you have a native * pointers to the module instance memory obtained with * wasm_runtime_addr_app_to_native or similar APIs. * * @param module_inst the WASM module instance which contains heap * @param size the size bytes to allocate * @param p_native_addr return native address of the allocated memory * if it is not NULL, and return NULL if memory malloc failed * * @return the allocated memory address, which is a relative offset to the * base address of the module instance's memory space. Note that * it is not an absolute address. * Return non-zero if success, zero if failed. */ WASM_RUNTIME_API_EXTERN uint64_t wasm_runtime_module_malloc(wasm_module_inst_t module_inst, uint64_t size, void **p_native_addr); /** * Free memory to the heap of WASM module instance * * @param module_inst the WASM module instance which contains heap * @param ptr the pointer to free */ WASM_RUNTIME_API_EXTERN void wasm_runtime_module_free(wasm_module_inst_t module_inst, uint64_t ptr); /** * Allocate memory from the heap of WASM module instance and initialize * the memory with src * * @param module_inst the WASM module instance which contains heap * @param src the source data to copy * @param size the size of the source data * * @return the allocated memory address, which is a relative offset to the * base address of the module instance's memory space. Note that * it is not an absolute address. * Return non-zero if success, zero if failed. */ WASM_RUNTIME_API_EXTERN uint64_t wasm_runtime_module_dup_data(wasm_module_inst_t module_inst, const char *src, uint64_t size); /** * Validate the app address, check whether it belongs to WASM module * instance's address space, or in its heap space or memory space. * * @param module_inst the WASM module instance * @param app_offset the app address to validate, which is a relative address * @param size the size bytes of the app address * * @return true if success, false otherwise. If failed, an exception will * be thrown. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_validate_app_addr(wasm_module_inst_t module_inst, uint64_t app_offset, uint64_t size); /** * Similar to wasm_runtime_validate_app_addr(), except that the size parameter * is not provided. This function validates the app string address, check * whether it belongs to WASM module instance's address space, or in its heap * space or memory space. Moreover, it checks whether it is the offset of a * string that is end with '\0'. * * Note: The validation result, especially the NUL termination check, * is not reliable for a module instance with multiple threads because * other threads can modify the heap behind us. * * @param module_inst the WASM module instance * @param app_str_offset the app address of the string to validate, which is a * relative address * * @return true if success, false otherwise. If failed, an exception will * be thrown. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_validate_app_str_addr(wasm_module_inst_t module_inst, uint64_t app_str_offset); /** * Validate the native address, check whether it belongs to WASM module * instance's address space, or in its heap space or memory space. * * @param module_inst the WASM module instance * @param native_ptr the native address to validate, which is an absolute * address * @param size the size bytes of the app address * * @return true if success, false otherwise. If failed, an exception will * be thrown. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_validate_native_addr(wasm_module_inst_t module_inst, void *native_ptr, uint64_t size); /** * Convert app address(relative address) to native address(absolute address) * * Note that native addresses to module instance memory can be invalidated * on a memory growth. (Except shared memory, whose native addresses are * stable.) * * @param module_inst the WASM module instance * @param app_offset the app address * * @return the native address converted */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_addr_app_to_native(wasm_module_inst_t module_inst, uint64_t app_offset); /** * Convert native address(absolute address) to app address(relative address) * * @param module_inst the WASM module instance * @param native_ptr the native address * * @return the app address converted */ WASM_RUNTIME_API_EXTERN uint64_t wasm_runtime_addr_native_to_app(wasm_module_inst_t module_inst, void *native_ptr); /** * Get the app address range (relative address) that a app address belongs to * * @param module_inst the WASM module instance * @param app_offset the app address to retrieve * @param p_app_start_offset buffer to output the app start offset if not NULL * @param p_app_end_offset buffer to output the app end offset if not NULL * * @return true if success, false otherwise. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_get_app_addr_range(wasm_module_inst_t module_inst, uint64_t app_offset, uint64_t *p_app_start_offset, uint64_t *p_app_end_offset); /** * Get the native address range (absolute address) that a native address * belongs to * * @param module_inst the WASM module instance * @param native_ptr the native address to retrieve * @param p_native_start_addr buffer to output the native start address * if not NULL * @param p_native_end_addr buffer to output the native end address * if not NULL * * @return true if success, false otherwise. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_get_native_addr_range(wasm_module_inst_t module_inst, uint8_t *native_ptr, uint8_t **p_native_start_addr, uint8_t **p_native_end_addr); /** * Get the number of import items for a WASM module * * @param module the WASM module * * @return the number of imports (zero for none), or -1 for failure */ WASM_RUNTIME_API_EXTERN int32_t wasm_runtime_get_import_count(const wasm_module_t module); /** * Get information about a specific WASM module import * * @param module the WASM module * @param import_index the desired import index * @param import_type the location to store information about the import */ WASM_RUNTIME_API_EXTERN void wasm_runtime_get_import_type(const wasm_module_t module, int32_t import_index, wasm_import_t *import_type); /** * Get the number of export items for a WASM module * * @param module the WASM module * * @return the number of exports (zero for none), or -1 for failure */ WASM_RUNTIME_API_EXTERN int32_t wasm_runtime_get_export_count(const wasm_module_t module); /** * Get information about a specific WASM module export * * @param module the WASM module * @param export_index the desired export index * @param export_type the location to store information about the export */ WASM_RUNTIME_API_EXTERN void wasm_runtime_get_export_type(const wasm_module_t module, int32_t export_index, wasm_export_t *export_type); /** * Get the number of parameters for a function type * * @param func_type the function type * * @return the number of parameters for the function type */ WASM_RUNTIME_API_EXTERN uint32_t wasm_func_type_get_param_count(wasm_func_type_t const func_type); /** * Get the kind of a parameter for a function type * * @param func_type the function type * @param param_index the index of the parameter to get * * @return the kind of the parameter if successful, -1 otherwise */ WASM_RUNTIME_API_EXTERN wasm_valkind_t wasm_func_type_get_param_valkind(wasm_func_type_t const func_type, uint32_t param_index); /** * Get the number of results for a function type * * @param func_type the function type * * @return the number of results for the function type */ WASM_RUNTIME_API_EXTERN uint32_t wasm_func_type_get_result_count(wasm_func_type_t const func_type); /** * Get the kind of a result for a function type * * @param func_type the function type * @param result_index the index of the result to get * * @return the kind of the result if successful, -1 otherwise */ WASM_RUNTIME_API_EXTERN wasm_valkind_t wasm_func_type_get_result_valkind(wasm_func_type_t const func_type, uint32_t result_index); /** * Get the kind for a global type * * @param global_type the global type * * @return the kind of the global */ WASM_RUNTIME_API_EXTERN wasm_valkind_t wasm_global_type_get_valkind(const wasm_global_type_t global_type); /** * Get the mutability for a global type * * @param global_type the global type * * @return true if mutable, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_global_type_get_mutable(const wasm_global_type_t global_type); /** * Get the shared setting for a memory type * * @param memory_type the memory type * * @return true if shared, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_memory_type_get_shared(const wasm_memory_type_t memory_type); /** * Get the initial page count for a memory type * * @param memory_type the memory type * * @return the initial memory page count */ WASM_RUNTIME_API_EXTERN uint32_t wasm_memory_type_get_init_page_count(const wasm_memory_type_t memory_type); /** * Get the maximum page count for a memory type * * @param memory_type the memory type * * @return the maximum memory page count */ WASM_RUNTIME_API_EXTERN uint32_t wasm_memory_type_get_max_page_count(const wasm_memory_type_t memory_type); /** * Register native functions with same module name * * Note: The array `native_symbols` should not be read-only because the * library can modify it in-place. * * Note: After successful call of this function, the array `native_symbols` * is owned by the library. * * @param module_name the module name of the native functions * @param native_symbols specifies an array of NativeSymbol structures which * contain the names, function pointers and signatures * Note: WASM runtime will not allocate memory to clone the data, so * user must ensure the array can be used forever * Meanings of letters in function signature: * 'i': the parameter is i32 type * 'I': the parameter is i64 type * 'f': the parameter is f32 type * 'F': the parameter is f64 type * 'r': the parameter is externref type, it should be a uintptr_t * in host * '*': the parameter is a pointer (i32 in WASM), and runtime will * auto check its boundary before calling the native function. * If it is followed by '~', the checked length of the pointer * is gotten from the following parameter, if not, the checked * length of the pointer is 1. * '~': the parameter is the pointer's length with i32 type, and must * follow after '*' * '$': the parameter is a string (i32 in WASM), and runtime will * auto check its boundary before calling the native function * @param n_native_symbols specifies the number of native symbols in the array * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_register_natives(const char *module_name, NativeSymbol *native_symbols, uint32_t n_native_symbols); /** * Register native functions with same module name, similar to * wasm_runtime_register_natives, the difference is that runtime passes raw * arguments to native API, which means that the native API should be defined as * void foo(wasm_exec_env_t exec_env, uint64 *args); * and native API should extract arguments one by one from args array with macro * native_raw_get_arg * and write the return value back to args[0] with macro * native_raw_return_type and native_raw_set_return */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_register_natives_raw(const char *module_name, NativeSymbol *native_symbols, uint32_t n_native_symbols); /** * Undo wasm_runtime_register_natives or wasm_runtime_register_natives_raw * * @param module_name Should be the same as the corresponding * wasm_runtime_register_natives. * (Same in term of strcmp.) * * @param native_symbols Should be the same as the corresponding * wasm_runtime_register_natives. * (Same in term of pointer comparison.) * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_unregister_natives(const char *module_name, NativeSymbol *native_symbols); /** * Get an export global instance * * @param module_inst the module instance * @param name the export global name * @param global_inst location to store the global instance * * @return true if success, false otherwise * */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_get_export_global_inst(const wasm_module_inst_t module_inst, const char *name, wasm_global_inst_t *global_inst); /** * Get attachment of native function from execution environment * * @param exec_env the execution environment to retrieve * * @return the attachment of native function */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_get_function_attachment(wasm_exec_env_t exec_env); /** * Set user data to execution environment. * * @param exec_env the execution environment * @param user_data the user data to be set */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_user_data(wasm_exec_env_t exec_env, void *user_data); /** * Get the user data within execution environment. * * @param exec_env the execution environment * * @return the user data (NULL if not set yet) */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_get_user_data(wasm_exec_env_t exec_env); /** * Dump runtime memory consumption, including: * Exec env memory consumption * WASM module memory consumption * WASM module instance memory consumption * stack and app heap used info * * @param exec_env the execution environment */ WASM_RUNTIME_API_EXTERN void wasm_runtime_dump_mem_consumption(wasm_exec_env_t exec_env); /** * Dump runtime performance profiler data of each function * * @param module_inst the WASM module instance to profile */ WASM_RUNTIME_API_EXTERN void wasm_runtime_dump_perf_profiling(wasm_module_inst_t module_inst); /** * Return total wasm functions' execution time in ms * * @param module_inst the WASM module instance to profile */ WASM_RUNTIME_API_EXTERN double wasm_runtime_sum_wasm_exec_time(wasm_module_inst_t module_inst); /** * Return execution time in ms of a given wasm function with * func_name. If the function is not found, return 0. * * @param module_inst the WASM module instance to profile * @param func_name could be an export name or a name in the * name section */ WASM_RUNTIME_API_EXTERN double wasm_runtime_get_wasm_func_exec_time(wasm_module_inst_t inst, const char *func_name); /* wasm thread callback function type */ typedef void *(*wasm_thread_callback_t)(wasm_exec_env_t, void *); /* wasm thread type */ typedef uintptr_t wasm_thread_t; /** * Set the max thread num per cluster. * * @param num maximum thread num */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_max_thread_num(uint32_t num); /** * Spawn a new exec_env, the spawned exec_env * can be used in other threads * * @param num the original exec_env * * @return the spawned exec_env if success, NULL otherwise */ WASM_RUNTIME_API_EXTERN wasm_exec_env_t wasm_runtime_spawn_exec_env(wasm_exec_env_t exec_env); /** * Destroy the spawned exec_env * * @param exec_env the spawned exec_env */ WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_spawned_exec_env(wasm_exec_env_t exec_env); /** * Spawn a thread from the given exec_env * * @param exec_env the original exec_env * @param tid thread id to be returned to the caller * @param callback the callback function provided by the user * @param arg the arguments passed to the callback * * @return 0 if success, -1 otherwise */ WASM_RUNTIME_API_EXTERN int32_t wasm_runtime_spawn_thread(wasm_exec_env_t exec_env, wasm_thread_t *tid, wasm_thread_callback_t callback, void *arg); /** * Wait a spawned thread to terminate * * @param tid thread id * @param retval if not NULL, output the return value of the thread * * @return 0 if success, error number otherwise */ WASM_RUNTIME_API_EXTERN int32_t wasm_runtime_join_thread(wasm_thread_t tid, void **retval); /** * Map external object to an internal externref index: if the index * has been created, return it, otherwise create the index. * * @param module_inst the WASM module instance that the extern object * belongs to * @param extern_obj the external object to be mapped * @param p_externref_idx return externref index of the external object * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_externref_obj2ref(wasm_module_inst_t module_inst, void *extern_obj, uint32_t *p_externref_idx); /** * Delete external object registered by `wasm_externref_obj2ref`. * * @param module_inst the WASM module instance that the extern object * belongs to * @param extern_obj the external object to be deleted * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_externref_objdel(wasm_module_inst_t module_inst, void *extern_obj); /** * Set cleanup callback to release external object. * * @param module_inst the WASM module instance that the extern object * belongs to * @param extern_obj the external object to which to set the * `extern_obj_cleanup` cleanup callback. * @param extern_obj_cleanup a callback to release `extern_obj` * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_externref_set_cleanup(wasm_module_inst_t module_inst, void *extern_obj, void (*extern_obj_cleanup)(void *)); /** * Retrieve the external object from an internal externref index * * @param externref_idx the externref index to retrieve * @param p_extern_obj return the mapped external object of * the externref index * * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_externref_ref2obj(uint32_t externref_idx, void **p_extern_obj); /** * Retain an extern object which is mapped to the internal externref * so that the object won't be cleaned during extern object reclaim * if it isn't used. * * @param externref_idx the externref index of an external object * to retain * @return true if success, false otherwise */ WASM_RUNTIME_API_EXTERN bool wasm_externref_retain(uint32_t externref_idx); /** * Dump the call stack to stdout * * @param exec_env the execution environment */ WASM_RUNTIME_API_EXTERN void wasm_runtime_dump_call_stack(wasm_exec_env_t exec_env); /** * Get the size required to store the call stack contents, including * the space for terminating null byte ('\0') * * @param exec_env the execution environment * * @return size required to store the contents, 0 means error */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_get_call_stack_buf_size(wasm_exec_env_t exec_env); /** * Dump the call stack to buffer. * * @note this function is not thread-safe, please only use this API * when the exec_env is not executing * * @param exec_env the execution environment * @param buf buffer to store the dumped content * @param len length of the buffer * * @return bytes dumped to the buffer, including the terminating null * byte ('\0'), 0 means error and data in buf may be invalid */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_dump_call_stack_to_buf(wasm_exec_env_t exec_env, char *buf, uint32_t len); /** * Get the size required to store the LLVM PGO profile data * * @param module_inst the WASM module instance * * @return size required to store the contents, 0 means error */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_get_pgo_prof_data_size(wasm_module_inst_t module_inst); /** * Dump the LLVM PGO profile data to buffer * * @param module_inst the WASM module instance * @param buf buffer to store the dumped content * @param len length of the buffer * * @return bytes dumped to the buffer, 0 means error and data in buf * may be invalid */ WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_dump_pgo_prof_data_to_buf(wasm_module_inst_t module_inst, char *buf, uint32_t len); /** * Get a custom section by name * * @param module_comm the module to find * @param name name of the custom section * @param len return the length of the content if found * * @return Custom section content (not including the name length * and name string) if found, NULL otherwise */ WASM_RUNTIME_API_EXTERN const uint8_t * wasm_runtime_get_custom_section(wasm_module_t const module_comm, const char *name, uint32_t *len); /** * Get WAMR semantic version */ WASM_RUNTIME_API_EXTERN void wasm_runtime_get_version(uint32_t *major, uint32_t *minor, uint32_t *patch); /** * Check whether an import func `(import (func ...))` * is linked or not with runtime registered native functions */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_import_func_linked(const char *module_name, const char *func_name); /** * Check whether an import global `(import * (global ...))` is linked or not with runtime registered native globals */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_import_global_linked(const char *module_name, const char *global_name); typedef enum { INTERNAL_ERROR, MAX_SIZE_REACHED, } enlarge_memory_error_reason_t; typedef void (*enlarge_memory_error_callback_t)( uint32_t inc_page_count, uint64_t current_memory_size, uint32_t memory_index, enlarge_memory_error_reason_t failure_reason, wasm_module_inst_t instance, wasm_exec_env_t exec_env, void *user_data); /** * Setup callback invoked when memory.grow fails */ WASM_RUNTIME_API_EXTERN void wasm_runtime_set_enlarge_mem_error_callback( const enlarge_memory_error_callback_t callback, void *user_data); /* * module instance context APIs * wasm_runtime_create_context_key * wasm_runtime_destroy_context_key * wasm_runtime_set_context * wasm_runtime_set_context_spread * wasm_runtime_get_context * * This set of APIs is intended to be used by an embedder which provides * extra sets of native functions, which need per module instance state * and are maintained outside of the WAMR tree. * * It's modelled after the pthread specific API. * * wasm_runtime_set_context_spread is similar to * wasm_runtime_set_context, except that * wasm_runtime_set_context_spread applies the change * to all threads in the cluster. * It's an undefined behavior if multiple threads in a cluster call * wasm_runtime_set_context_spread on the same key * simultaneously. It's a caller's responsibility to perform necessary * serialization if necessary. For example: * * if (wasm_runtime_get_context(inst, key) == NULL) { * newctx = alloc_and_init(...); * lock(some_lock); * if (wasm_runtime_get_context(inst, key) == NULL) { * // this thread won the race * wasm_runtime_set_context_spread(inst, key, newctx); * newctx = NULL; * } * unlock(some_lock); * if (newctx != NULL) { * // this thread lost the race, free it * cleanup_and_free(newctx); * } * } * * Note: dynamic key create/destroy while instances are live is not * implemented as of writing this. * it's caller's responsibility to ensure destroying all module instances * before calling wasm_runtime_create_context_key or * wasm_runtime_destroy_context_key. * otherwise, it's an undefined behavior. * * Note about threads: * - When spawning a thread, the contexts (the pointers given to * wasm_runtime_set_context) are copied from the parent * instance. * - The destructor is called only on the main instance. */ WASM_RUNTIME_API_EXTERN void * wasm_runtime_create_context_key(void (*dtor)(wasm_module_inst_t inst, void *ctx)); WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_context_key(void *key); WASM_RUNTIME_API_EXTERN void wasm_runtime_set_context(wasm_module_inst_t inst, void *key, void *ctx); WASM_RUNTIME_API_EXTERN void wasm_runtime_set_context_spread(wasm_module_inst_t inst, void *key, void *ctx); WASM_RUNTIME_API_EXTERN void * wasm_runtime_get_context(wasm_module_inst_t inst, void *key); /* * wasm_runtime_begin_blocking_op/wasm_runtime_end_blocking_op * * These APIs are intended to be used by the implementations of * host functions. It wraps an operation which possibly blocks for long * to prepare for async termination. * * For simplicity, we recommend to wrap only the very minimum piece of * the code with this. Ideally, just a single system call. * * eg. * * if (!wasm_runtime_begin_blocking_op(exec_env)) { * return EINTR; * } * ret = possibly_blocking_op(); * wasm_runtime_end_blocking_op(exec_env); * return ret; * * If threading support (WASM_ENABLE_THREAD_MGR) is not enabled, * these functions are no-op. * * If the underlying platform support (OS_ENABLE_WAKEUP_BLOCKING_OP) is * not available, these functions are no-op. In that case, the runtime * might not terminate a blocking thread in a timely manner. * * If the underlying platform support is available, it's used to wake up * the thread for async termination. The expectation here is that a * `os_wakeup_blocking_op` call makes the blocking operation * (`possibly_blocking_op` in the above example) return in a timely manner. * * The actual wake up mechanism used by `os_wakeup_blocking_op` is * platform-dependent. It might impose some platform-dependent restrictions * on the implementation of the blocking operation. * * For example, on POSIX-like platforms, a signal (by default SIGUSR1) is * used. The signal delivery configurations (eg. signal handler, signal mask, * etc) for the signal are set up by the runtime. You can change the signal * to use for this purpose by calling os_set_signal_number_for_blocking_op * before the runtime initialization. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_begin_blocking_op(wasm_exec_env_t exec_env); WASM_RUNTIME_API_EXTERN void wasm_runtime_end_blocking_op(wasm_exec_env_t exec_env); WASM_RUNTIME_API_EXTERN bool wasm_runtime_set_module_name(wasm_module_t module, const char *name, char *error_buf, uint32_t error_buf_size); /* return the most recently set module name or "" if never set before */ WASM_RUNTIME_API_EXTERN const char * wasm_runtime_get_module_name(wasm_module_t module); /* * wasm_runtime_detect_native_stack_overflow * * Detect native stack shortage. * Ensure that the calling thread still has a reasonable amount of * native stack (WASM_STACK_GUARD_SIZE bytes) available. * * If enough stack is left, this function returns true. * Otherwise, this function raises a "native stack overflow" trap and * returns false. * * Note: please do not expect a very strict detection. it's a good idea * to give some margins. wasm_runtime_detect_native_stack_overflow itself * requires a small amount of stack to run. */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_detect_native_stack_overflow(wasm_exec_env_t exec_env); /* * wasm_runtime_detect_native_stack_overflow_size * * Similar to wasm_runtime_detect_native_stack_overflow, * but use the caller-specified size instead of WASM_STACK_GUARD_SIZE. * * An expected usage: * ```c * __attribute__((noinline)) // inlining can break the stack check * void stack_hog(void) * { * // consume a lot of stack here * } * * void * stack_hog_wrapper(exec_env) { * // the amount of stack stack_hog would consume, * // plus a small margin * uint32_t size = 10000000; * * if (!wasm_runtime_detect_native_stack_overflow_size(exec_env, size)) { * // wasm_runtime_detect_native_stack_overflow_size has raised * // a trap. * return; * } * stack_hog(); * } * ``` */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_detect_native_stack_overflow_size(wasm_exec_env_t exec_env, uint32_t required_size); /** * Query whether the wasm binary buffer used to create the module can be freed * * @param module the target module * @return true if the wasm binary buffer can be freed */ WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_underlying_binary_freeable(const wasm_module_t module); #ifdef __cplusplus } #endif #endif /* end of _WASM_EXPORT_H */