Confusing syntax in API documentation

[osa1]

Looking at https://github.com/WebAssembly/WASI/blob/master/phases/snapshot/docs.md

For example, the function environ_sizes_get is shown as environ_sizes_get() -> (errno, size, size). This looks like it's returning three values, but if I compile a simple program to WASI this is the type of the function:

  (type (;3;) (func (param i32 i32) (result i32)))
  ...
  (import "wasi_snapshot_preview1" "environ_sizes_get" (func $__wasi_environ_sizes_get (type 3)))

So it's actually taking two args and returning one value.

I have no idea what the args are, I'm guessing they're memory locations to return values, first one is for errno, second one is for the first size, but I'm not sure. It'd be good to describe the syntax in the API docs.

[caspervonb]

This looks like it's returning three values

Yes, post MVP has support for multiple return values.

I have no idea what the args are, I'm guessing they're memory locations to return values

Yes they're memory offsets when they point to structures but size is just a primitive, u64 IIRC.

[pchickey]

At the moment, we're bound by the LLVM wasm32 ABI for return values after the first to be passed in by reference. The multiple return value (multi-value) proposal is part of the spec now (https://github.com/WebAssembly/proposals/blob/master/finished-proposals.md), but we don't use it in WASI yet.

We're working towards independence from the LLVM wasm32 ABI through the Interface Types proposal. The witx spec format is designed to mimic the concepts in the Interface Types proposal, and we are working for the two to converge, but Interface Types is still under active development and afaik there are no implementations of it yet.

[sbc100]

Still, it might be nice to somehow include the actual wasm signatures of the functions as they exist today no?

Looking that C header can help, but even then that is not low level enough for someone who might want to actually implement the interface.

Where does the currently lowering from "witx" style to "actual wasm signatures as they exist today" happen?

[pchickey]

The witx crate has a programmatic description of the lowering, but we dont render that into the docs. There's no particular reason why we couldn't. https://docs.rs/witx/0.8.7/witx/struct.InterfaceFunc.html#method.core_type

[yagehu]

Yes! Getting the exact function signature to WASI functions is a pain. I'm working on writing Wasm text format programs that verify basic WASI syscall support, and clearer documentation will help a lot. I think most runtimes (Wasmer, WAVM, etc.) by default don't support multiple return values.

[sbc100]

Indeed, its kind of mute point thought because the WASI API is defined today as not using multi-return, regardless of whether the runtime supports it. Like other features WASI will want to wait because it adopts such things in the core API.

[turbolent]

Did anyone find a description for the function signatures of the MVP variant, i.e. ones that only have a single return value?

[sbc100]

Did you try looking at the C header? I think that is the current best description of the low level signatures of each of the API functions: https://github.com/WebAssembly/wasi-libc/blob/main/libc-bottom-half/headers/public/wasi/api.h

[turbolent]

@sbc100 Perfect, thank you!