Example of how to embed

[violetastcs]

I believe there should be an example somewhere in the repo, demonstrating how to embed the runtime into people's own applications, along with examples of exposing functions, and any other possible runtime manipulations (assuming all of this is possible in the project's current state)

[sunfishcode]

In the tree, we have this example. Outside the tree, we have the simplejit-demo and Wasmtime.

That said, there's certainly room for improvement, both in the examples and the APIs to streamline common use cases. I'd be interested if you could describe what you're looking to do, and how things could be improved to better help you.

Perhaps to start with, would it help if we moved simplejit-minimal.rs to a top-level examples directory, rather than having under lib/simplejit/examples?

[sunfishcode]

Ah, reading this again, I see that this issue is for Wasmtime, not Cranelift itself. So disregard my previous message :-}.

Currently, the best example we have is src/wasmtime.rs in the main tree, which is the command-line driver for the libraries. It shows how to load a wasm module, instantiate it, and invoke functions on it.

I agree that we need more examples :-) For now, if there's anything you have questions about, feel free to ask!

[maxmcd]

A few questions in the same vein. I have a messy working example using wasmtime. (The code is here)

I've taken most of my inspiration from the spectests. Is the expectation that external functions will be defined on a separate module and then called between modules? In getting a simple rust wasm example working with a print statement I have most of the code from src/wasmtime.rs and then I define a separate module with the external function I want to call: https://github.com/maxmcd/wasm-servers/blob/master/runtime/src/resolver.rs#L154-L197

In order to share memory between modules I effectively copy and paste InstancePlus::new and add this line: https://github.com/maxmcd/wasm-servers/blob/master/runtime/src/instance_plus_plus.rs#L39-L41

Seems a little awkward at the moment, but I'm sure it can be cleaned up. No pressure to go through my code, but more generally would be great to hear your thoughts on what the structure of a simple foreign function example would look like.

[sunfishcode]

Yes, if you want functions defined by the host, the main expected way to do that is to put them in their own module, similar to the spectest module. Hopefully we'll have more examples of that soon. That's not the only way it can be done, but it does simplify some things, such a code caching (which isn't implemented yet, but which is anticipated in the current design) because we can then just cache a whole module as a unit.

The APIs for doing this aren't very streamlined yet, but I'm working on it. One thing I'm specifically working on right now is extracting out parts of the WastContext functionality from lib/wast for loading multiple modules and making their exports automatically available for subsequent imports.

Modifying the module manually, to add a memory import, is somewhat awkward. Ideally, the wasm module itself should have an import, so that the VM doesn't need to inject it itself.

That said, there is a broader issue where you want to have module A use functions from module B, and then those functions need to access memory from module A. This will likely get solved for real when host-bindings arrives, allowing us to pass slices of memory around as parameters. Until then, we need a temporary solution, and we're still experimenting with various options.

[maxmcd]

Would the expectation be that the cache is portable? Even some kind of binary format that would represent a compiled .wasm?

Thanks for the clarifications. Those WastContext changes sound great.

[maxmcd]

One more question: the wasmtime_call_trampoline passes a VMContext. If a user of the wasmtime lib wanted to pass more context to the function calls is the expectation that one would write their own call trampoline?

As a simple example let's say I wanted to mock out environment variables, and hold them in a hashmap within the runtime. I write my own InstancePlus::invoke and sort out my own call trampoline?

I guess it makes a lot of sense to just implement a custom InstancePlus-type struct with the desired functionality?

[sunfishcode]

Would the expectation be that the cache is portable? Even some kind of binary format that would represent a compiled .wasm?

I haven't thought much about the format of the cache yet, but at the very least, it'll contain machine code, so it won't be portable between hardware architectures, nor between operating systems with different calling conventions (eg. Windows vs. everything else on x86-64).

One possible direction here is to build out lib/obj and src/wasm2obj.rs in the tree, which is an early experiment writing out a native object file containing compiled wasm code, so that we can use them for caching too.

One more question: the wasmtime_call_trampoline passes a VMContext. If a user of the wasmtime lib wanted to pass more context to the function calls is the expectation that one would write their own call trampoline?

The functions called by wasm_call_trampoline handle calling from dynamically constructed calls into compiled wasm code. Wasm-to-wasm calls don't go through wasmtime_call_trampoline. So if you want extra arguments passed to wasm functions in general, the trampoline logic won't be sufficient.

I'm expecting to introduce some "global" runtime state soon, where each Instance will have a pointer to this state. We need this to properly implement the shared signature table, and a shared code registry, and other things, and then one option is to adopt an idea @lachlansneff suggested to me a while ago, to add a way for embedders to add their own data to this. That way, you could add your data, and get to it when given a VMContext pointer. Does that sound like it would work?

[maxmcd]

Ah yes, whoops, keep tricking myself into thinking wasm_call_trampoline is more than just the single invoke call.

That solution sounds like it would work. Covers all of my current use cases.

[sunfishcode]

Working on some host module implementations, it looks like it's more convenient to have per-instance state than global state. In 73b2c45 and 3ac4269, I've how added a host_state field within Instance, which is a Box<dyn Any> which you can initialize in Instance's new and access via host_state() on Instance or VMContext. That's a general-purpose mechanism which I think covers the needs here, but I'd be interested to hear about any case where it isn't sufficient.

[maxmcd]

Very much a fan of per-instance state. Looks good to me.

I'm trying to update my code with the new changes. (&mut *vmctx).instance_contents() (formerly instance) is now private. How should one access shared memory with a vmctx? Is it up to me to make that available in host_state?

[maxmcd]

Got the new structure working. Really helps clean things up.

For memory access I do this:

let mut instance = instantiate(compiler, &data, &mut namespace).map_err(|e| e.to_string())?;

let definition = match instance.lookup("mem") {
    Some(wasmtime_runtime::Export::Memory {
        definition,
        memory: _memory,
        vmctx: _vmctx,
    }) => definition,
    Some(_) => panic!("exported item is not a linear memory",),
    None => panic!("no export "),
};

let go_instance = &mut namespace.instances[go_index];
let host_state = go_instance
    .host_state()
    .downcast_mut::<resolver::SharedState>()
    .expect("did not downcase a SharedState");
host_state.definition = Some(definition);

Grab the memory from the instantiated instance and add it to the host_state. I end up having to add pub to namespace.instances to allow access after the instance has been added to the namespace. My Rust knowledge might be failing me here, maybe I can just hold a reference to the ShareState. Any thoughts on this structure, or how to accomplish without modifying wasmtime?

[buckle2000]

Still, how do I expose func in rust to wasm module?

[sunfishcode]

Assuming func is exported, you can call lookup to look it up by name. That gives you Export, which assuming its an Export::Function, gives you the function address which you can cast to a rust function reference, and the vmctx argument to pass to it. Alternatively, you an use the invoke function to do a lot of this for you, though it'll use a trampoline rather than a direct call.

That's what's currently possible. In the future, I'm hoping we'll have more ergonomic utilities to wrap this functionality.

[sunfishcode]

Got the new structure working. Really helps clean things up.

Cool!

For memory access I do this:

let mut instance = instantiate(compiler, &data, &mut namespace).map_err(|e| e.to_string())?;

let definition = match instance.lookup("mem") {
    Some(wasmtime_runtime::Export::Memory {
        definition,
        memory: _memory,
        vmctx: _vmctx,
    }) => definition,
    Some(_) => panic!("exported item is not a linear memory",),
    None => panic!("no export "),
};

let go_instance = &mut namespace.instances[go_index];
let host_state = go_instance
    .host_state()
    .downcast_mut::<resolver::SharedState>()
    .expect("did not downcase a SharedState");
host_state.definition = Some(definition);

Grab the memory from the instantiated instance and add it to the host_state. I end up having to add pub to namespace.instances to allow access after the instance has been added to the namespace. My Rust knowledge might be failing me here, maybe I can just hold a reference to the ShareState. Any thoughts on this structure, or how to accomplish without modifying wasmtime?

Hmm, there should probably be an accessor that returns the instance for a given InstanceIndex, which if I understand correctly would do what you need here.

[buckle2000]

Sorry, I mean the other way around. "How do I expose rust function to webassembly module?"

I already know how, but the code itself is confusing; especially foo as *const VMFunctionBody.

    let env_instance = InstanceBuilder::new()
        .register_func(
            "foo".to_owned(),
            foo as *const VMFunctionBody,
            vec![ir::AbiParam::new(ir::types::I32)],
            vec![] )
        .build()
        .unwrap();

    namespace.instance(Some("env"), env_instance);

There should be a macro for this.