This file defines the exported common runtime APIs. More...

#include <stdint.h>
#include <stdbool.h>
#include "lib_export.h"

Include dependency graph for wasm_export.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	wasm_section_t

union	MemAllocOption

struct	mem_alloc_info_t

struct	RuntimeInitArgs

struct	InstantiationArgs

struct	wasm_val_t

Macros
#define	WASM_RUNTIME_API_EXTERN

#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)

#define	WASM_MODULE_T_DEFINED

#define	MEM_ALLOC_OPTION_DEFINED

#define	INSTANTIATION_ARGS_OPTION_DEFINED

#define	WASM_VALKIND_T_DEFINED

#define	WASM_VAL_T_DEFINED

Typedefs
typedef struct WASMModuleCommon *	wasm_module_t

typedef struct WASMModuleInstanceCommon *	wasm_module_inst_t

typedef void	WASMFunctionInstanceCommon

typedef WASMFunctionInstanceCommon *	wasm_function_inst_t

typedef struct wasm_section_t	wasm_section_t

typedef struct wasm_section_t	aot_section_t

typedef struct wasm_section_t *	wasm_section_list_t

typedef struct wasm_section_t *	aot_section_list_t

typedef struct WASMExecEnv *	wasm_exec_env_t

typedef union MemAllocOption	MemAllocOption

typedef struct mem_alloc_info_t	mem_alloc_info_t

typedef enum RunningMode	RunningMode

typedef struct RuntimeInitArgs	RuntimeInitArgs

typedef struct InstantiationArgs	InstantiationArgs

typedef uint8_t	wasm_valkind_t

typedef struct wasm_val_t	wasm_val_t

typedef bool(*	module_reader) (package_type_t module_type, const char module_name, uint8_t p_buffer, uint32_t p_size)

typedef void(*	module_destroyer) (uint8_t *buffer, uint32_t size)

typedef void (	wasm_thread_callback_t) (wasm_exec_env_t, void *)

typedef uintptr_t	wasm_thread_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)

Enumerations
enum	package_type_t { Wasm_Module_Bytecode = 0, Wasm_Module_AoT, Package_Type_Unknown = 0xFFFF }

enum	mem_alloc_type_t { Alloc_With_Pool = 0, Alloc_With_Allocator, Alloc_With_System_Allocator, Alloc_With_Pool = 0, Alloc_With_Allocator, Alloc_With_System_Allocator }

enum	RunningMode { Mode_Interp = 1, Mode_Fast_JIT, Mode_LLVM_JIT, Mode_Multi_Tier_JIT }

enum	wasm_valkind_enum { WASM_I32, WASM_I64, WASM_F32, WASM_F64, WASM_ANYREF = 128, WASM_FUNCREF, WASM_I32, WASM_I64, WASM_F32, WASM_F64, WASM_ANYREF = 128, WASM_FUNCREF }

enum	log_level_t { 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 }

enum	enlarge_memory_error_reason_t { INTERNAL_ERROR, MAX_SIZE_REACHED }

Functions
WASM_RUNTIME_API_EXTERN bool	wasm_runtime_init (void)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_full_init (RuntimeInitArgs *init_args)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_log_level (log_level_t level)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_is_running_mode_supported (RunningMode running_mode)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_set_default_running_mode (RunningMode running_mode)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_destroy (void)

WASM_RUNTIME_API_EXTERN void *	wasm_runtime_malloc (unsigned int size)

WASM_RUNTIME_API_EXTERN void *	wasm_runtime_realloc (void *ptr, unsigned int size)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_free (void *ptr)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_get_mem_alloc_info (mem_alloc_info_t *mem_alloc_info)

WASM_RUNTIME_API_EXTERN package_type_t	get_package_type (const uint8_t *buf, uint32_t size)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_is_xip_file (const uint8_t *buf, uint32_t size)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_module_reader (const module_reader reader, const module_destroyer destroyer)

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)

WASM_RUNTIME_API_EXTERN wasm_module_t	wasm_runtime_find_module_registered (const char *module_name)

WASM_RUNTIME_API_EXTERN wasm_module_t	wasm_runtime_load (uint8_t buf, uint32_t size, char error_buf, uint32_t error_buf_size)

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)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_unload (wasm_module_t module)

char *	wasm_runtime_get_module_hash (wasm_module_t module)

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)

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)

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)

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)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_set_running_mode (wasm_module_inst_t module_inst, RunningMode running_mode)

WASM_RUNTIME_API_EXTERN RunningMode	wasm_runtime_get_running_mode (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_deinstantiate (wasm_module_inst_t module_inst)

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)

WASM_RUNTIME_API_EXTERN uint32_t	wasm_runtime_get_wasi_exit_code (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN wasm_function_inst_t	wasm_runtime_lookup_function (wasm_module_inst_t const module_inst, const char *name)

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)

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)

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)

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)

WASM_RUNTIME_API_EXTERN wasm_exec_env_t	wasm_runtime_create_exec_env (wasm_module_inst_t module_inst, uint32_t stack_size)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_destroy_exec_env (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN wasm_exec_env_t	wasm_runtime_get_exec_env_singleton (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN uint32_t	wasm_runtime_start_debug_instance_with_port (wasm_exec_env_t exec_env, int32_t port)

WASM_RUNTIME_API_EXTERN uint32_t	wasm_runtime_start_debug_instance (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_init_thread_env (void)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_destroy_thread_env (void)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_thread_env_inited (void)

WASM_RUNTIME_API_EXTERN wasm_module_inst_t	wasm_runtime_get_module_inst (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_module_inst (wasm_exec_env_t exec_env, const wasm_module_inst_t module_inst)

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[])

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)

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,...)

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[])

WASM_RUNTIME_API_EXTERN bool	wasm_application_execute_main (wasm_module_inst_t module_inst, int32_t argc, char *argv[])

WASM_RUNTIME_API_EXTERN bool	wasm_application_execute_func (wasm_module_inst_t module_inst, const char name, int32_t argc, char argv[])

const WASM_RUNTIME_API_EXTERN char *	wasm_runtime_get_exception (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_exception (wasm_module_inst_t module_inst, const char *exception)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_clear_exception (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_terminate (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_custom_data (wasm_module_inst_t module_inst, void *custom_data)

WASM_RUNTIME_API_EXTERN void *	wasm_runtime_get_custom_data (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_bounds_checks (wasm_module_inst_t module_inst, bool enable)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_is_bounds_checks_enabled (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN uint64_t	wasm_runtime_module_malloc (wasm_module_inst_t module_inst, uint64_t size, void **p_native_addr)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_module_free (wasm_module_inst_t module_inst, uint64_t ptr)

WASM_RUNTIME_API_EXTERN uint64_t	wasm_runtime_module_dup_data (wasm_module_inst_t module_inst, const char *src, uint64_t size)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_validate_app_addr (wasm_module_inst_t module_inst, uint64_t app_offset, uint64_t size)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_validate_app_str_addr (wasm_module_inst_t module_inst, uint64_t app_str_offset)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_validate_native_addr (wasm_module_inst_t module_inst, void *native_ptr, uint64_t size)

WASM_RUNTIME_API_EXTERN void *	wasm_runtime_addr_app_to_native (wasm_module_inst_t module_inst, uint64_t app_offset)

WASM_RUNTIME_API_EXTERN uint64_t	wasm_runtime_addr_native_to_app (wasm_module_inst_t module_inst, void *native_ptr)

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)

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)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_register_natives (const char module_name, NativeSymbol native_symbols, uint32_t n_native_symbols)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_register_natives_raw (const char module_name, NativeSymbol native_symbols, uint32_t n_native_symbols)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_unregister_natives (const char module_name, NativeSymbol native_symbols)

WASM_RUNTIME_API_EXTERN void *	wasm_runtime_get_function_attachment (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_user_data (wasm_exec_env_t exec_env, void *user_data)

WASM_RUNTIME_API_EXTERN void *	wasm_runtime_get_user_data (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_dump_mem_consumption (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_dump_perf_profiling (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN double	wasm_runtime_sum_wasm_exec_time (wasm_module_inst_t module_inst)

WASM_RUNTIME_API_EXTERN double	wasm_runtime_get_wasm_func_exec_time (wasm_module_inst_t inst, const char *func_name)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_max_thread_num (uint32_t num)

WASM_RUNTIME_API_EXTERN wasm_exec_env_t	wasm_runtime_spawn_exec_env (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_destroy_spawned_exec_env (wasm_exec_env_t exec_env)

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)

WASM_RUNTIME_API_EXTERN int32_t	wasm_runtime_join_thread (wasm_thread_t tid, void **retval)

WASM_RUNTIME_API_EXTERN bool	wasm_externref_obj2ref (wasm_module_inst_t module_inst, void extern_obj, uint32_t p_externref_idx)

WASM_RUNTIME_API_EXTERN bool	wasm_externref_objdel (wasm_module_inst_t module_inst, void *extern_obj)

WASM_RUNTIME_API_EXTERN bool	wasm_externref_set_cleanup (wasm_module_inst_t module_inst, void extern_obj, void(extern_obj_cleanup)(void *))

WASM_RUNTIME_API_EXTERN bool	wasm_externref_ref2obj (uint32_t externref_idx, void **p_extern_obj)

WASM_RUNTIME_API_EXTERN bool	wasm_externref_retain (uint32_t externref_idx)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_dump_call_stack (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN uint32_t	wasm_runtime_get_call_stack_buf_size (wasm_exec_env_t exec_env)

WASM_RUNTIME_API_EXTERN uint32_t	wasm_runtime_dump_call_stack_to_buf (wasm_exec_env_t exec_env, char *buf, uint32_t len)

WASM_RUNTIME_API_EXTERN uint32_t	wasm_runtime_get_pgo_prof_data_size (wasm_module_inst_t module_inst)

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)

const WASM_RUNTIME_API_EXTERN uint8_t *	wasm_runtime_get_custom_section (wasm_module_t const module_comm, const char name, uint32_t len)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_get_version (uint32_t major, uint32_t minor, uint32_t *patch)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_is_import_func_linked (const char module_name, const char func_name)

WASM_RUNTIME_API_EXTERN bool	wasm_runtime_is_import_global_linked (const char module_name, const char global_name)

WASM_RUNTIME_API_EXTERN void	wasm_runtime_set_enlarge_mem_error_callback (const enlarge_memory_error_callback_t callback, void *user_data)

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_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)

const WASM_RUNTIME_API_EXTERN char *	wasm_runtime_get_module_name (wasm_module_t module)

Detailed Description

This file defines the exported common runtime APIs.

Date: Wed Mar 20 10:46:38 2024

Typedef Documentation

◆ module_destroyer

typedef void(* module_destroyer) (uint8_t *buffer, uint32_t size)

Callback to release the buffer loaded by module_reader callback

◆ module_reader

typedef bool(* module_reader) (package_type_t module_type, const char *module_name, uint8_t **p_buffer, uint32_t *p_size)

Callback to load a module file into a buffer in multi-module feature

Function Documentation

◆ get_package_type()

WASM_RUNTIME_API_EXTERN package_type_t get_package_type	(	const uint8_t *	buf,
		uint32_t	size
	)

Get the package type of a buffer.

Parameters

buf	the package buffer
size	the package buffer size

Returns: the package type, return Package_Type_Unknown if the type is unknown

◆ wasm_application_execute_func()

WASM_RUNTIME_API_EXTERN bool wasm_application_execute_func	(	wasm_module_inst_t	module_inst,
		const char *	name,
		int32_t	argc,
		char *	argv[]
	)

Find the specified function in argv[0] from a WASM module instance and execute that function.

Parameters

module_inst	the WASM module instance
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
argc	the number of arguments
argv	the arguments array

Returns: 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_application_execute_main()

WASM_RUNTIME_API_EXTERN bool wasm_application_execute_main	(	wasm_module_inst_t	module_inst,
		int32_t	argc,
		char *	argv[]
	)

Find the unique main function from a WASM module instance and execute that function.

Parameters

module_inst	the WASM module instance
argc	the number of arguments
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.

Returns: 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_externref_obj2ref()

WASM_RUNTIME_API_EXTERN bool wasm_externref_obj2ref	(	wasm_module_inst_t	module_inst,
		void *	extern_obj,
		uint32_t *	p_externref_idx
	)

Map external object to an internal externref index: if the index has been created, return it, otherwise create the index.

Parameters

module_inst	the WASM module instance that the extern object belongs to
extern_obj	the external object to be mapped
p_externref_idx	return externref index of the external object

Returns: true if success, false otherwise

◆ wasm_externref_objdel()

WASM_RUNTIME_API_EXTERN bool wasm_externref_objdel	(	wasm_module_inst_t	module_inst,
		void *	extern_obj
	)

Delete external object registered by wasm_externref_obj2ref.

Parameters

module_inst	the WASM module instance that the extern object belongs to
extern_obj	the external object to be deleted

Returns: true if success, false otherwise

◆ wasm_externref_ref2obj()

WASM_RUNTIME_API_EXTERN bool wasm_externref_ref2obj	(	uint32_t	externref_idx,
		void **	p_extern_obj
	)

Retrieve the external object from an internal externref index

Parameters

externref_idx	the externref index to retrieve
p_extern_obj	return the mapped external object of the externref index

Returns: true if success, false otherwise

◆ wasm_externref_retain()

WASM_RUNTIME_API_EXTERN bool wasm_externref_retain ( uint32_t externref_idx )

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.

Parameters

externref_idx the externref index of an external object to retain

Returns: true if success, false otherwise

◆ wasm_externref_set_cleanup()

WASM_RUNTIME_API_EXTERN bool wasm_externref_set_cleanup	(	wasm_module_inst_t	module_inst,
		void *	extern_obj,
		void()(void )	extern_obj_cleanup
	)

Set cleanup callback to release external object.

Parameters

module_inst	the WASM module instance that the extern object belongs to
extern_obj	the external object to which to set the `extern_obj_cleanup` cleanup callback.
extern_obj_cleanup	a callback to release `extern_obj`

Returns: true if success, false otherwise

◆ wasm_func_get_param_count()

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 parameter count of the function instance

Parameters

func_inst	the function instance
module_inst	the module instance the function instance belongs to

Returns: the parameter count of the function instance

◆ wasm_func_get_param_types()

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 parameter types of the function instance

Parameters

func_inst	the function instance
module_inst	the module instance the function instance belongs to
param_types	the parameter types returned

◆ wasm_func_get_result_count()

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 result count of the function instance

Parameters

func_inst	the function instance
module_inst	the module instance the function instance belongs to

Returns: the result count of the function instance

◆ wasm_func_get_result_types()

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
	)

Get result types of the function instance

Parameters

func_inst	the function instance
module_inst	the module instance the function instance belongs to
result_types	the result types returned

◆ wasm_runtime_addr_app_to_native()

WASM_RUNTIME_API_EXTERN void* wasm_runtime_addr_app_to_native	(	wasm_module_inst_t	module_inst,
		uint64_t	app_offset
	)

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.)

Parameters

module_inst	the WASM module instance
app_offset	the app adress

Returns: the native address converted

◆ wasm_runtime_addr_native_to_app()

WASM_RUNTIME_API_EXTERN uint64_t wasm_runtime_addr_native_to_app	(	wasm_module_inst_t	module_inst,
		void *	native_ptr
	)

Convert native address(absolute address) to app address(relative address)

Parameters

module_inst	the WASM module instance
native_ptr	the native address

Returns: the app address converted

◆ wasm_runtime_call_indirect()

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[]
	)

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.

Parameters

exec_env	the execution environment to call the function which must be created from wasm_create_exec_env()
element_index	the function reference index, usually prvovided by the caller of a registed native function
argc	the number of arguments
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.

Returns: true if success, false otherwise and exception will be thrown, the caller can call wasm_runtime_get_exception to get exception info.

◆ wasm_runtime_call_wasm()

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 arguments (bytecode and AoT).

Parameters

exec_env	the execution environment to call the function, which must be created from wasm_create_exec_env()
function	the function to call
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
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.

Returns: 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_call_wasm_a()

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 arguments (bytecode and AoT).

Parameters

exec_env	the execution environment to call the function, which must be created from wasm_create_exec_env()
function	the function to call
num_results	the number of results
results	the pre-alloced pointer to get the results
num_args	the number of arguments
args	the arguments

Returns: 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_call_wasm_v()

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 the given WASM function of a WASM module instance with provided results space and variant arguments (bytecode and AoT).

Parameters

exec_env	the execution environment to call the function, which must be created from wasm_create_exec_env()
function	the function to call
num_results	the number of results
results	the pre-alloced pointer to get the results
num_args	the number of arguments
...	the variant arguments

Returns: 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_clear_exception()

WASM_RUNTIME_API_EXTERN void wasm_runtime_clear_exception ( wasm_module_inst_t module_inst )

Clear exception info of the WASM module instance.

Parameters

module_inst the WASM module instance

◆ wasm_runtime_create_exec_env()

WASM_RUNTIME_API_EXTERN wasm_exec_env_t wasm_runtime_create_exec_env	(	wasm_module_inst_t	module_inst,
		uint32_t	stack_size
	)

Create execution environment for a WASM module instance.

Parameters

module_inst	the module instance
stack_size	the stack size to execute a WASM function

Returns: the execution environment, NULL if failed, e.g. invalid stack size is passed

◆ wasm_runtime_deinstantiate()

WASM_RUNTIME_API_EXTERN void wasm_runtime_deinstantiate ( wasm_module_inst_t module_inst )

Deinstantiate a WASM module instance, destroy the resources.

Parameters

module_inst the WASM module instance to destroy

◆ wasm_runtime_destroy()

WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy ( void )

Destroy the WASM runtime environment.

◆ wasm_runtime_destroy_exec_env()

WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_exec_env ( wasm_exec_env_t exec_env )

Destroy the execution environment.

Parameters

exec_env the execution environment to destroy

◆ wasm_runtime_destroy_spawned_exec_env()

WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_spawned_exec_env ( wasm_exec_env_t exec_env )

Destroy the spawned exec_env

Parameters

exec_env the spawned exec_env

◆ wasm_runtime_destroy_thread_env()

WASM_RUNTIME_API_EXTERN void wasm_runtime_destroy_thread_env ( void )

Destroy the thread environment

◆ wasm_runtime_dump_call_stack()

WASM_RUNTIME_API_EXTERN void wasm_runtime_dump_call_stack ( wasm_exec_env_t exec_env )

Dump the call stack to stdout

Parameters

exec_env the execution environment

◆ wasm_runtime_dump_call_stack_to_buf()

WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_dump_call_stack_to_buf	(	wasm_exec_env_t	exec_env,
		char *	buf,
		uint32_t	len
	)

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

Parameters

exec_env	the execution environment
buf	buffer to store the dumped content
len	length of the buffer

Returns: bytes dumped to the buffer, including the terminating null byte ('\0'), 0 means error and data in buf may be invalid

◆ wasm_runtime_dump_mem_consumption()

WASM_RUNTIME_API_EXTERN void wasm_runtime_dump_mem_consumption ( 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

Parameters

exec_env the execution environment

◆ wasm_runtime_dump_perf_profiling()

WASM_RUNTIME_API_EXTERN void wasm_runtime_dump_perf_profiling ( wasm_module_inst_t module_inst )

Dump runtime performance profiler data of each function

Parameters

module_inst the WASM module instance to profile

◆ wasm_runtime_dump_pgo_prof_data_to_buf()

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
	)

Dump the LLVM PGO profile data to buffer

Parameters

module_inst	the WASM module instance
buf	buffer to store the dumped content
len	length of the buffer

Returns: bytes dumped to the buffer, 0 means error and data in buf may be invalid

◆ wasm_runtime_find_module_registered()

WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_find_module_registered ( const char * module_name )

Check if there is already a loaded module named module_name in the runtime. Repeately loading a module with the same name is not allowed.

Parameters

module_name indicate a name

Returns: return WASM module loaded, NULL if failed

◆ wasm_runtime_full_init()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_full_init ( RuntimeInitArgs * init_args )

Initialize the WASM runtime environment, WASM running mode, and also initialize the memory allocator and register native symbols, which are specified with init arguments

Parameters

init_args specifies the init arguments

Returns: return true if success, false otherwise

◆ wasm_runtime_get_app_addr_range()

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 app address range (relative address) that a app address belongs to

Parameters

module_inst	the WASM module instance
app_offset	the app address to retrieve
p_app_start_offset	buffer to output the app start offset if not NULL
p_app_end_offset	buffer to output the app end offset if not NULL

Returns: true if success, false otherwise.

◆ wasm_runtime_get_call_stack_buf_size()

WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_get_call_stack_buf_size ( wasm_exec_env_t exec_env )

Get the size required to store the call stack contents, including the space for terminating null byte ('\0')

Parameters

exec_env the execution environment

Returns: size required to store the contents, 0 means error

◆ wasm_runtime_get_custom_data()

WASM_RUNTIME_API_EXTERN void* wasm_runtime_get_custom_data ( wasm_module_inst_t module_inst )

Get the custom data within a WASM module instance.

Parameters

module_inst the WASM module instance

Returns: the custom data (NULL if not set yet)

◆ wasm_runtime_get_custom_section()

const WASM_RUNTIME_API_EXTERN uint8_t* wasm_runtime_get_custom_section	(	wasm_module_t const	module_comm,
		const char *	name,
		uint32_t *	len
	)

Get a custom section by name

Parameters

module_comm	the module to find
name	name of the custom section
len	return the length of the content if found

Returns: Custom section content (not including the name length and name string) if found, NULL otherwise

◆ wasm_runtime_get_exception()

const WASM_RUNTIME_API_EXTERN char* wasm_runtime_get_exception ( wasm_module_inst_t module_inst )

Get exception info of the WASM module instance.

Parameters

module_inst the WASM module instance

Returns: the exception string

◆ wasm_runtime_get_exec_env_singleton()

WASM_RUNTIME_API_EXTERN wasm_exec_env_t wasm_runtime_get_exec_env_singleton ( wasm_module_inst_t module_inst )

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.

Parameters

module_inst the module instance

Returns: exec_env the execution environment to destroy

◆ wasm_runtime_get_function_attachment()

WASM_RUNTIME_API_EXTERN void* wasm_runtime_get_function_attachment ( wasm_exec_env_t exec_env )

Get attachment of native function from execution environment

Parameters

exec_env the execution environment to retrieve

Returns: the attachment of native function

◆ wasm_runtime_get_module()

WASM_RUNTIME_API_EXTERN wasm_module_t wasm_runtime_get_module ( wasm_module_inst_t module_inst )

Get WASM module from WASM module instance

Parameters

module_inst the WASM module instance to retrieve

Returns: the WASM module

◆ wasm_runtime_get_module_hash()

char* wasm_runtime_get_module_hash ( 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

Parameters

module the WASM module to retrieve

Returns: the module hash of the WASM module

◆ wasm_runtime_get_module_inst()

WASM_RUNTIME_API_EXTERN wasm_module_inst_t wasm_runtime_get_module_inst ( wasm_exec_env_t exec_env )

Get WASM module instance from execution environment

Parameters

exec_env the execution environment to retrieve

Returns: the WASM module instance

◆ wasm_runtime_get_native_addr_range()

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 native address range (absolute address) that a native address belongs to

Parameters

module_inst	the WASM module instance
native_ptr	the native address to retrieve
p_native_start_addr	buffer to output the native start address if not NULL
p_native_end_addr	buffer to output the native end address if not NULL

Returns: true if success, false otherwise.

◆ wasm_runtime_get_pgo_prof_data_size()

WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_get_pgo_prof_data_size ( wasm_module_inst_t module_inst )

Get the size required to store the LLVM PGO profile data

Parameters

module_inst the WASM module instance

Returns: size required to store the contents, 0 means error

◆ wasm_runtime_get_running_mode()

WASM_RUNTIME_API_EXTERN RunningMode wasm_runtime_get_running_mode ( wasm_module_inst_t module_inst )

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.

Parameters

module_inst the WASM module instance to query for running mode

Returns: the running mode this module instance currently use

◆ wasm_runtime_get_user_data()

WASM_RUNTIME_API_EXTERN void* wasm_runtime_get_user_data ( wasm_exec_env_t exec_env )

Get the user data within execution environment.

Parameters

exec_env the execution environment

Returns: the user data (NULL if not set yet)

◆ wasm_runtime_get_version()

WASM_RUNTIME_API_EXTERN void wasm_runtime_get_version	(	uint32_t *	major,
		uint32_t *	minor,
		uint32_t *	patch
	)

Get WAMR semantic version

◆ wasm_runtime_get_wasi_exit_code()

WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_get_wasi_exit_code ( 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.)

Parameters

module_inst the module instance

◆ wasm_runtime_get_wasm_func_exec_time()

WASM_RUNTIME_API_EXTERN double wasm_runtime_get_wasm_func_exec_time	(	wasm_module_inst_t	inst,
		const char *	func_name
	)

Return execution time in ms of a given wasm funciton with func_name. If the function is not found, return 0.

Parameters

module_inst	the WASM module instance to profile
func_name	could be an export name or a name in the name section

◆ wasm_runtime_init()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_init ( void )

Initialize the WASM runtime environment, and also initialize the memory allocator with system allocator, which calls os_malloc to allocate memory

Returns: true if success, false otherwise

◆ wasm_runtime_init_thread_env()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_init_thread_env ( void )

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.

Returns: true if success, false otherwise

◆ wasm_runtime_instantiate()

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.

Parameters

module	the WASM module to instantiate
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.
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.
error_buf	buffer to output the error info if failed
error_buf_size	the size of the error buffer

Returns: return the instantiated WASM module instance, NULL if failed

◆ wasm_runtime_instantiate_ex()

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
	)

Instantiate a WASM module, with specified instantiation arguments

Same as wasm_runtime_instantiate, but it also allows overwriting maximum memory

◆ wasm_runtime_is_bounds_checks_enabled()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_bounds_checks_enabled ( wasm_module_inst_t module_inst )

Check if the memory bounds checks flag is enabled for a WASM module instance.

Parameters

module_inst the WASM module instance

Returns: true if the memory bounds checks flag is enabled, false otherwise

◆ wasm_runtime_is_import_func_linked()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_import_func_linked	(	const char *	module_name,
		const char *	func_name
	)

Check whether an import func (import <module_name> <func_name> (func ...)) is linked or not with runtime registered natvie functions

◆ wasm_runtime_is_import_global_linked()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_import_global_linked	(	const char *	module_name,
		const char *	global_name
	)

Check whether an import global (import <module_name> <global_name> (global ...)) is linked or not with runtime registered natvie globals

◆ wasm_runtime_is_running_mode_supported()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_running_mode_supported ( RunningMode running_mode )

Query whether a certain running mode is supported for the runtime

Parameters

running_mode the running mode to query

Returns: true if this running mode is supported, false otherwise

◆ wasm_runtime_is_xip_file()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_is_xip_file	(	const uint8_t *	buf,
		uint32_t	size
	)

Check whether a file is an AOT XIP (Execution In Place) file

Parameters

buf	the package buffer
size	the package buffer size

Returns: true if success, false otherwise

◆ wasm_runtime_join_thread()

WASM_RUNTIME_API_EXTERN int32_t wasm_runtime_join_thread	(	wasm_thread_t	tid,
		void **	retval
	)

Wait a spawned thread to terminate

Parameters

tid	thread id
retval	if not NULL, output the return value of the thread

Returns: 0 if success, error number otherwise

◆ wasm_runtime_load()

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 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.

Parameters

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 referencable until wasm_runtime_unload is called
size	the size of the buffer
error_buf	output of the exception info
error_buf_size	the size of the exception string

Returns: return WASM module loaded, NULL if failed

◆ wasm_runtime_load_from_sections()

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
	)

Load a WASM module from a specified WASM or AOT section list.

Parameters

section_list	the section list which contains each section data
is_aot	whether the section list is AOT section list
error_buf	output of the exception info
error_buf_size	the size of the exception string

Returns: return WASM module loaded, NULL if failed

◆ wasm_runtime_lookup_function()

WASM_RUNTIME_API_EXTERN wasm_function_inst_t wasm_runtime_lookup_function	(	wasm_module_inst_t const	module_inst,
		const char *	name
	)

Lookup an exported function in the WASM module instance.

Parameters

module_inst	the module instance
name	the name of the function

Returns: the function instance found, NULL if not found

◆ wasm_runtime_malloc()

WASM_RUNTIME_API_EXTERN void* wasm_runtime_malloc ( unsigned int size )

Allocate memory from runtime memory environment.

Parameters

size	bytes need to allocate

Returns: the pointer to memory allocated

◆ wasm_runtime_module_dup_data()

WASM_RUNTIME_API_EXTERN uint64_t wasm_runtime_module_dup_data	(	wasm_module_inst_t	module_inst,
		const char *	src,
		uint64_t	size
	)

Allocate memory from the heap of WASM module instance and initialize the memory with src

Parameters

module_inst	the WASM module instance which contains heap
src	the source data to copy
size	the size of the source data

Returns: 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_module_free()

WASM_RUNTIME_API_EXTERN void wasm_runtime_module_free	(	wasm_module_inst_t	module_inst,
		uint64_t	ptr
	)

Free memory to the heap of WASM module instance

Parameters

module_inst	the WASM module instance which contains heap
ptr	the pointer to free

◆ wasm_runtime_module_malloc()

WASM_RUNTIME_API_EXTERN uint64_t wasm_runtime_module_malloc	(	wasm_module_inst_t	module_inst,
		uint64_t	size,
		void **	p_native_addr
	)

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.

Parameters

module_inst	the WASM module instance which contains heap
size	the size bytes to allocate
p_native_addr	return native address of the allocated memory if it is not NULL, and return NULL if memory malloc failed

Returns: 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_realloc()

WASM_RUNTIME_API_EXTERN void* wasm_runtime_realloc	(	void *	ptr,
		unsigned int	size
	)

Reallocate memory from runtime memory environment

Parameters

ptr	the original memory
size	bytes need to reallocate

Returns: the pointer to memory reallocated

◆ wasm_runtime_register_module()

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
	)

Give the "module" a name "module_name". Can not assign a new name to a module if it already has a name

Parameters

module_name	indicate a name
module	the target module
error_buf	output of the exception info
error_buf_size	the size of the exception string

Returns: true means success, false means failed

◆ wasm_runtime_register_natives()

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

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.

Parameters

module_name	the module name of the native functions
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
n_native_symbols	specifies the number of native symbols in the array

Returns: true if success, false otherwise

◆ wasm_runtime_register_natives_raw()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_register_natives_raw	(	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_set_bounds_checks()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_bounds_checks	(	wasm_module_inst_t	module_inst,
		bool	enable
	)

Set the memory bounds checks flag of a WASM module instance.

Parameters

module_inst	the WASM module instance
enable	the flag to enable/disable the memory bounds checks

◆ wasm_runtime_set_custom_data()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_custom_data	(	wasm_module_inst_t	module_inst,
		void *	custom_data
	)

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

Parameters

module_inst	the WASM module instance
custom_data	the custom data to be set

◆ wasm_runtime_set_default_running_mode()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_set_default_running_mode ( 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

Parameters

running_mode the running mode to set

Returns: true if success, false otherwise

◆ wasm_runtime_set_enlarge_mem_error_callback()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_enlarge_mem_error_callback	(	const enlarge_memory_error_callback_t	callback,
		void *	user_data
	)

Setup callback invoked when memory.grow fails

◆ wasm_runtime_set_exception()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_exception	(	wasm_module_inst_t	module_inst,
		const char *	exception
	)

Set exception info of the WASM module instance.

Parameters

module_inst	the WASM module instance
exception	the exception string

◆ wasm_runtime_set_log_level()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_log_level ( log_level_t level )

Set the log level. To be called after the runtime is initialized.

Parameters

level the log level to set

◆ wasm_runtime_set_max_thread_num()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_max_thread_num ( uint32_t num )

Set the max thread num per cluster.

Parameters

num	maximum thread num

◆ wasm_runtime_set_module_inst()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_module_inst	(	wasm_exec_env_t	exec_env,
		const wasm_module_inst_t	module_inst
	)

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

Parameters

exec_env	the execution environment
module_inst	the WASM module instance to set

◆ wasm_runtime_set_module_reader()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_module_reader	(	const module_reader	reader,
		const module_destroyer	destroyer
	)

Setup callbacks for reading and releasing a buffer about a module file

Parameters

reader	a callback to read a module file into a buffer
destroyer	a callback to release above buffer

◆ wasm_runtime_set_running_mode()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_set_running_mode	(	wasm_module_inst_t	module_inst,
		RunningMode	running_mode
	)

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.

Parameters

module_inst	the WASM module instance to set running mode
running_mode	the running mode to set

Returns: true if success, false otherwise

◆ wasm_runtime_set_user_data()

WASM_RUNTIME_API_EXTERN void wasm_runtime_set_user_data	(	wasm_exec_env_t	exec_env,
		void *	user_data
	)

Set user data to execution environment.

Parameters

exec_env	the execution environment
user_data	the user data to be set

◆ wasm_runtime_set_wasi_args()

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
	)

Set WASI parameters.

Same as wasm_runtime_set_wasi_args_ex but with default stdio handles

◆ wasm_runtime_set_wasi_args_ex()

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.

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().

Parameters

module	The module to set WASI parameters.
dir_list	The list of directories to preopen. (real path)
dir_count	The number of elements in dir_list.
map_dir_list	The list of directories to preopen. (mapped path) Format for each map entry: <guest-path>::<host-path>
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.
env	The list of environment variables.
env_count	The number of elements in env.
argv	The list of command line arguments.
argc	The number of elements in argv.
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.
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.
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_spawn_exec_env()

WASM_RUNTIME_API_EXTERN wasm_exec_env_t wasm_runtime_spawn_exec_env ( wasm_exec_env_t exec_env )

Spawn a new exec_env, the spawned exec_env can be used in other threads

Parameters

num	the original exec_env

Returns: the spawned exec_env if success, NULL otherwise

◆ wasm_runtime_spawn_thread()

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
	)

Spawn a thread from the given exec_env

Parameters

exec_env	the original exec_env
tid	thread id to be returned to the caller
callback	the callback function provided by the user
arg	the arguments passed to the callback

Returns: 0 if success, -1 otherwise

◆ wasm_runtime_start_debug_instance()

WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_start_debug_instance ( wasm_exec_env_t exec_env )

Same as wasm_runtime_start_debug_instance_with_port(env, -1).

◆ wasm_runtime_start_debug_instance_with_port()

WASM_RUNTIME_API_EXTERN uint32_t wasm_runtime_start_debug_instance_with_port	(	wasm_exec_env_t	exec_env,
		int32_t	port
	)

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.

Parameters

exec_env	the execution environment to start debug instance
port	the port for the debug server to listen on. 0 means automatic assignment. -1 means to use the global setting in RuntimeInitArgs.

Returns: debug port if success, 0 otherwise.

◆ wasm_runtime_sum_wasm_exec_time()

WASM_RUNTIME_API_EXTERN double wasm_runtime_sum_wasm_exec_time ( wasm_module_inst_t module_inst )

Return total wasm functions' execution time in ms

Parameters

module_inst the WASM module instance to profile

◆ wasm_runtime_terminate()

WASM_RUNTIME_API_EXTERN void wasm_runtime_terminate ( 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.

Parameters

module_inst the WASM module instance

◆ wasm_runtime_thread_env_inited()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_thread_env_inited ( void )

Whether the thread environment is initialized

◆ wasm_runtime_unload()

WASM_RUNTIME_API_EXTERN void wasm_runtime_unload ( wasm_module_t module )

Unload a WASM module.

Parameters

module the module to be unloaded

◆ wasm_runtime_unregister_natives()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_unregister_natives	(	const char *	module_name,
		NativeSymbol *	native_symbols
	)

Undo wasm_runtime_register_natives or wasm_runtime_register_natives_raw

Parameters

module_name	Should be the same as the corresponding wasm_runtime_register_natives. (Same in term of strcmp.)
native_symbols	Should be the same as the corresponding wasm_runtime_register_natives. (Same in term of pointer comparison.)

Returns: true if success, false otherwise

◆ wasm_runtime_validate_app_addr()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_validate_app_addr	(	wasm_module_inst_t	module_inst,
		uint64_t	app_offset,
		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.

Parameters

module_inst	the WASM module instance
app_offset	the app address to validate, which is a relative address
size	the size bytes of the app address

Returns: true if success, false otherwise. If failed, an exception will be thrown.

◆ wasm_runtime_validate_app_str_addr()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_validate_app_str_addr	(	wasm_module_inst_t	module_inst,
		uint64_t	app_str_offset
	)

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.

Parameters

module_inst	the WASM module instance
app_str_offset	the app address of the string to validate, which is a relative address

Returns: true if success, false otherwise. If failed, an exception will be thrown.

◆ wasm_runtime_validate_native_addr()

WASM_RUNTIME_API_EXTERN bool wasm_runtime_validate_native_addr	(	wasm_module_inst_t	module_inst,
		void *	native_ptr,
		uint64_t	size
	)

Validate the native address, check whether it belongs to WASM module instance's address space, or in its heap space or memory space.

Parameters

module_inst	the WASM module instance
native_ptr	the native address to validate, which is an absolute address
size	the size bytes of the app address

Returns: true if success, false otherwise. If failed, an exception will be thrown.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ module_destroyer

◆ module_reader

Function Documentation

◆ get_package_type()

◆ wasm_application_execute_func()

◆ wasm_application_execute_main()

◆ wasm_externref_obj2ref()

◆ wasm_externref_objdel()

◆ wasm_externref_ref2obj()

◆ wasm_externref_retain()

◆ wasm_externref_set_cleanup()

◆ wasm_func_get_param_count()

◆ wasm_func_get_param_types()

◆ wasm_func_get_result_count()

◆ wasm_func_get_result_types()

◆ wasm_runtime_addr_app_to_native()

◆ wasm_runtime_addr_native_to_app()

◆ wasm_runtime_call_indirect()

◆ wasm_runtime_call_wasm()

◆ wasm_runtime_call_wasm_a()

◆ wasm_runtime_call_wasm_v()

◆ wasm_runtime_clear_exception()

◆ wasm_runtime_create_exec_env()

◆ wasm_runtime_deinstantiate()

◆ wasm_runtime_destroy()

◆ wasm_runtime_destroy_exec_env()

◆ wasm_runtime_destroy_spawned_exec_env()

◆ wasm_runtime_destroy_thread_env()

◆ wasm_runtime_dump_call_stack()

◆ wasm_runtime_dump_call_stack_to_buf()

◆ wasm_runtime_dump_mem_consumption()

◆ wasm_runtime_dump_perf_profiling()

◆ wasm_runtime_dump_pgo_prof_data_to_buf()

◆ wasm_runtime_find_module_registered()

◆ wasm_runtime_full_init()

◆ wasm_runtime_get_app_addr_range()

◆ wasm_runtime_get_call_stack_buf_size()

◆ wasm_runtime_get_custom_data()

◆ wasm_runtime_get_custom_section()

◆ wasm_runtime_get_exception()

◆ wasm_runtime_get_exec_env_singleton()

◆ wasm_runtime_get_function_attachment()

◆ wasm_runtime_get_module()

◆ wasm_runtime_get_module_hash()

◆ wasm_runtime_get_module_inst()

◆ wasm_runtime_get_native_addr_range()

◆ wasm_runtime_get_pgo_prof_data_size()

◆ wasm_runtime_get_running_mode()

◆ wasm_runtime_get_user_data()

◆ wasm_runtime_get_version()

◆ wasm_runtime_get_wasi_exit_code()

◆ wasm_runtime_get_wasm_func_exec_time()

◆ wasm_runtime_init()

◆ wasm_runtime_init_thread_env()

◆ wasm_runtime_instantiate()

◆ wasm_runtime_instantiate_ex()

◆ wasm_runtime_is_bounds_checks_enabled()

◆ wasm_runtime_is_import_func_linked()

◆ wasm_runtime_is_import_global_linked()

◆ wasm_runtime_is_running_mode_supported()

◆ wasm_runtime_is_xip_file()

◆ wasm_runtime_join_thread()

◆ wasm_runtime_load()

◆ wasm_runtime_load_from_sections()

◆ wasm_runtime_lookup_function()

◆ wasm_runtime_malloc()

◆ wasm_runtime_module_dup_data()

◆ wasm_runtime_module_free()

◆ wasm_runtime_module_malloc()

◆ wasm_runtime_realloc()

◆ wasm_runtime_register_module()

◆ wasm_runtime_register_natives()

◆ wasm_runtime_register_natives_raw()