wasm-micro-runtime/doc/multi_module.md

Multiple Modules as Dependencies

A WASM module can import functions, globals, memories and tables from other modules as dependencies. A module can also export those entities for other modules like a library.

WAMR loads all dependencies recursively according to the import section of a module.

WAMR only implements the load-time dynamic linking. Please refer to dynamic linking for more details.

WAMR follows WASI Command/Reactor Model. The WASI model separates modules into commands and reactors. A Command is the main module that requires exports of reactors(submodules).

if WASM_ENABLE_LIBC_WASI is enabled, any module imports a WASI APIs, like (import "wasi_snapshot_preview1" "XXX"), should follow restrictions of the WASI application ABI:

• a main module(a command) should include _start()
• a submodule(a reactor) should include _initialize()
• both a command and a reactor should include an exported memory

Multi-Module Related APIs

Register a module

bool
wasm_runtime_register_module(const char *module_name,
                             wasm_module_t module,
                             char *error_buf,
                             uint32_t error_buf_size);

It is used to register a module with a module_name to WASM runtime, especially for the main module, which is loaded by wasm_runtime_load() and doesn't have a chance to tell runtime its module name.

WAMR will get submodules' names(according to the import section of the main module) and load .wasm files from the filesystem or stream and then register them internally.

Find a registered module

wasm_module_t
wasm_runtime_find_module_registered(
    const char *module_name);

It is used to check whether a module with a given module_name has been registered before or not. Return the module if yes.

Module reader and destroyer

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

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

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

WAMR hopes that the native host or embedding environment loads/unloads the module WASM files by themselves and only passes runtime the binary content without worrying about filesystem or storage issues. module_reader and module_destroyer are two callbacks called when dynamic-loading/unloading submodules. Developers must implement the two callbacks by themselves.

Call function of a submodule

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

Multi-module allows one to look up an exported function of a submodule. There are two ways to indicate the function name:

• parent function name only by default, used to look up the function of the parent module
• submodule name, function name and two $ symbols, e.g. $submodule_name$function_name, used to lookup function of submodule
• signature can be NULL

Example

Attributes in C/C++

Suppose there are three C files, mA.c, mB.c and mC.c. Each of them exports functions and imports from others except mA.

import/export with two kinds of __attribute__:

• __attribute__((import_module("MODULE_NAME"))) __attribute__((import_name("FUNCTION_NAME"))). to indicate dependencies of the current module.

• __attribute__((export_name("FUNCTION_NAME"))). to expose functions.

// mA.c
__attribute__((export_name("A1"))) int
A1()
{
    return 11;
}

// mB.c
__attribute__((import_module("mA")))
__attribute__((import_name("A1"))) extern int
A1();

__attribute__((export_name("B1"))) int
B1()
{
    return 21;
}

Compile Options

to generate a wasm module as a command

$ /path/to/wasi-sdk/bin/clang -o command.wasm main_module.c

to generate a wasm module as a reactor

$ /path/to/wasi-sdk/bin/clang -mexec-model=reactor -o reactor.wasm submodule.c

In the above case, mA and mB are reactors(submodules), mC is the command(main module). Their import relationships will be like:

libvmlib

We need to enable WAMR_BUILD_MULTI_MODULE option when building WAMR vmlib. Please ref to Build WAMR core for a thoughtful guide.

code

After all the preparation, we can call some functions from native code with APIs

First, create two callbacks to load WASM module files into memory and unload them later

static bool
module_reader_cb(const char *module_name, uint8 **p_buffer, uint32 *p_size)
{
  // ...
  *p_buffer = (uint8_t *)bh_read_file_to_buffer(wasm_file_path, p_size);
  // ...
}

static void
module_destroyer_cb(uint8 *buffer, uint32 size)
{
  BH_FREE(buffer);
}

Second, create a large buffer and tell WAMR malloc any resource only from this buffer later.

More details

static char sandbox_memory_space[10 * 1024 * 1024] = { 0 };

Third, put all together. Please refer to main.c