WAMR running mode control

[TianlongLiang]

Currently, WAMR running mode(Classic/Fast Interpreter, Fast JIT, LLVM JIT, or Multi-tier JIT) is determined at compile time by setting C macro. There is no way to choose a different running mode at execution time, even though the related code is also compiled and available. For example, we can’t run wasm code in Interpreter mode when Fast JIT is compiled, and if we want to use Interpreter mode, we will have to compile a new iwasm.

So we plan to add general APIs(when embedding WAMR) and CLI options(when using iwasm) to allow users to control the running mode at execution time.

When embedding WAMR

Running modes definition:

typedef enum RunningMode{
    Mode_Interp = 1, // classic interpreter
    Mode_Fast_JIT, // fast jit
    Mode_LLVM_JIT, // llvm jit
    Mode_Multi_Tier_JIT, // multi-tier jit
} RunningMode;

APIs can control running mode in different granularity:

• at runtime level:

  • add data member RunningMode running_mode for RuntimeInitArgs so that the user can initialize the default running mode using wasm_runtime_full_init(RuntimeInitArgs *init_args)
  • query whether a running mode is supported:

  bool wasm_runtime_is_running_mode_supported(RunningMode runnnig_mode);

  • set the default running mode for the entire runtime(for all module instances):

  bool wasm_runtime_set_default_running_mode(RunningMode runnnig_mode);

• at module instance level:

  • set the default running mode for a module instance

  bool wasm_runtime_set_running_mode(wasm_module_inst_t module_inst, RunningMode running_mode);

  • get the running mode for a module instance

  RunningMode wasm_runtime_get_running_mode(wasm_module_inst_t module_inst);

The priority of choosing running mode:

1. User set module instance running mode
2. User set default running mode
3. Compiled default running mode

When using iwasm

Four command line options to control the running mode of iwasm:

• --interp: run iwasm in class interpreter mode
• --fast-jit: run iwasm in fast jit mode
• --llvm-jit: run iwasm in llvm jit mode
• --multi-tier-jit: run iwasm in multi-tier jit mode

And two more command line options to control LLVM JIT's size and optimization level:

• --llvm-jit-opt-level=n: possible n values are 1, 2, 3. Currently, the opt level is hard coded to 3
• --llvm-jit-size-level=n: possible n values are 1, 2, 3. Currently, the size level is hard coded to 3

Example program/CLI usage

Example C program embedding WAMR:

...
init_args.running_mode = Mode_Fast_JIT;
...
// initialize the default running mode for entire runtime(all module instance)
wasm_runtime_full_init(&init_args);
...
// alternatively, you could set the default running mode the later
wasm_runtime_set_default_running_mode(Mode_Interp);
...
buffer = bh_read_file_to_buffer("a.wasm", &size);
module = wasm_runtime_load(buffer, size, error_buf, sizeof(error_buf));
module_inst = wasm_runtime_instantiate(module, stack_size, heap_size,error_buf, sizeof(error_buf));
...
// will run in default running mode
wasm_runtime_call_wasm(exec_env, a_func, 1, wasm_argv);
...
buffer_b = bh_read_file_to_buffer("b.wasm", &size);
module_b = wasm_runtime_load(buffer_b, size, error_buf, sizeof(error_buf));
module_inst_b = wasm_runtime_instantiate(module_b, stack_size, heap_size,error_buf, sizeof(error_buf));
wasm_runtime_set_running_mode(module_inst_b, Mode_Multi_Tier_JIT);
...
// will run in user set module instance running mode
wasm_runtime_call_wasm(exec_env, b_func, 1, wasm_argv);

Example iwasm CLI usage:

# compile multi-tier jit iwasm
cmake -B build --DWAMR_BUILD_INTERP=1 -DWAMR_BUILD_FAST_JIT=1 -DWAMR_BUILD_JIT=1
cmake --build build
# default mode: multi-tier jit will be run
iwasm test.wasm
# or could explicitly run multi-tier jit
iwasm --multi-tier-jit test.wasm
# choose to run llvm jit mode
iwasm --llvm-jit --llvm-jit-opt-level=3 test.wasm
# choose to run fast jit mode
iwasm --fast-jit test.wasm
# choose to run interpreter mode
iwasm --interp test.wasm

Subtasks and milestones

• [x] CLI options: four options for running mode for iwasm and APIs to set the runtime running mode
• [x] APIs to set the module instance running mode
• [x] CLI options: two options for LLVM JIT

[ttrenner]

Thats sounds to be a great thing, enhancing adaptability. But maybe there should be more options like "enabling debugging", "AOT-mode" etc.. Are there insights about the impacts?

[wenyongh]

Thats sounds to be a great thing, enhancing adaptability. But maybe there should be more options like "enabling debugging", "AOT-mode" etc.. Are there insights about the impacts?

Hi, the feature is only to control the running mode when the input is a wasm bytecode file: to run the wasm file with interpreter, fast-jit, llvm-jit or multi-tier-jit. It doesn't impact the AOT mode: if the input is AOT file, runtime always runs it with AOT mode.

For the "enabling debugging", I think if it is compiled, e.g. cmake -DWAMR_BUILD_DEBUG_INTERP, then developer can enter the interpreter mode to enable source debugging, e.g. iwasm --interp -g=ip:port <wasm_file>, no need to add an extra running mode.

BTW, we basically finished the coding the feature, refer to PR https://github.com/bytecodealliance/wasm-micro-runtime/pull/1890, now it is under testing. If you are interested in it, maybe you can have a try.