Add application-abi describing the current unstable WASI application ABI

[sbc100]

This is that start of a document regarding what we expect from a valid was WASI application. Not ready to land yet.

Does this kind of thing belong here? If not then where?

Perhaps I should include here documentation of the current status quo (i.e. _start function etc) along with the forward looking plans?

See #24 and #19

[sunfishcode]

What would you think about bring in Commands and Reactors as concepts here? Perhaps we could also add a third kind of thing: Libraries. (This may also help address #46).

Offhand:

WASI Reactors and WASI Libraries don't have a __wasi_main funtion.

WASI Commands just have a __wasi_main function and no __wasi_init function because it would be redundant -- they can do whatever initialization they need in their __wasi_main.

WASI Libraries don't define their own linear memories or tables (for now -- this restriction could be lifted in the future, but for now, WASI implementations need to know how to magically identify which linear memory to work with). WASI Libraries are loaded along with a WASI Reactor or a WASI Command and have the same lifetime.

Thoughts?

[sunfishcode]

For now, the module should be wasi_unstable until we rename it.

Also, while we're renaming things, can we rename "memory" to "__wasi_memory" too?

[sunfishcode]

It'd be good to mention how the wasm start function fits into this lifecycle as well.

[wanderer]

do we need to have the ability to both import and export memory? What would be the usecase for importing memory that isn't covered just by exporting?

[sbc100]

I was actually surprised to see that the wasi toolchain currently exports memory by default. I suppose that is because wasm-ld happens to have that is its default.

As a point of reference emscripten module import their memory from the embedder by default.

If we want to support sharing of memories the importing is the only way to go. If every module creates and exports it own memory there is no way they can access the same one.

I suppose we could start by documenting the status quo which is to export the memory from the module, and then extend this later as needed?

[sunfishcode]

It was also a conscious decision to have modules define their own memories -- looking forward to wasm modules compiled from languages which don't use linear memories, or which use multiple linear memories, it seems like it will be awkward for the host to try to provide exports for the things applications will need. The Command/Reactor/Library ontology can help here as well -- Commands and Reactors would (typically) define the main memory, and Libraries would (typically) import it.

[sbc100]

I paired down this PR to simply document the current ABI. Will move the rest to a followup.

[sunfishcode]

This looks good to me. We can leave this open a little longer to give people a chance to comment, but with the latest commits, it's now paired down (see @sbc100's comment) to just documenting the status quo, with pointers to ongoing discussions, so I don't expect it's controversial.

[xtuc]

@lukewagner @guybedford in nodejs/node#27850 (comment) we discussed the issue of running the main on import. However, this assumption seems to be wrong? Nodejs could decide to expose the _start function to the user.