From 93a490c83214f860664a4114eeb82cb623ca988c Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Thu, 30 May 2019 12:48:12 -0700 Subject: [PATCH 1/4] Add application-abi describing WASI application lifecycle --- design/application-abi.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 design/application-abi.md diff --git a/design/application-abi.md b/design/application-abi.md new file mode 100644 index 00000000..1324d966 --- /dev/null +++ b/design/application-abi.md @@ -0,0 +1,32 @@ +WASI Application ABI +==================== + +In addition to the APIs defined by the various WASI [modules](modules.md) there +are also certain expectations that the WASI runtime places on an application +that wishes to be portable across WASI implementations. + +This document describes how a conforming WASI application is expected to behave +in terms of lifecycle (startup, shutdown, etc) and imports and exports the that +it is expected to include. + +Lifecycle +--------- + +A WASI program may contain any number exports, but the embedded attributes +specific meaning the following optional function exports: + +- `__wasi_init` - Called after WebAssemembly instantiation but before any other + functions. +- `__wasi_main` - Runs the programs main entry points. May be omitted, for + example, in the case of a library. +- `__wasi_term` - The logical inverse of `__wasi_init`. Optionally called + before module destruction. No other functions within program will be called + after this one. + +Linear Memory +------------- + +All WASI programs are expected to share a linear memory with the embedder. The +memory can either be imported from the embedder or exports to the embedder. If +exported the memory must be named `__wasi_memory`. If imported the import must +be named `memory` from a module names `wasi`. From 04a609d2aa8e00c3fb08116680e55f2927fce112 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Fri, 31 May 2019 12:02:19 -0700 Subject: [PATCH 2/4] - document just the current ABI --- design/application-abi.md | 41 ++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/design/application-abi.md b/design/application-abi.md index 1324d966..5146ac3b 100644 --- a/design/application-abi.md +++ b/design/application-abi.md @@ -6,27 +6,32 @@ are also certain expectations that the WASI runtime places on an application that wishes to be portable across WASI implementations. This document describes how a conforming WASI application is expected to behave -in terms of lifecycle (startup, shutdown, etc) and imports and exports the that +in terms of lifecycle (startup, shutdown, etc) and any exports the that it is expected to include. -Lifecycle ---------- +Current Unstable ABI +-------------------- -A WASI program may contain any number exports, but the embedded attributes -specific meaning the following optional function exports: +The current WASI unstable ABI specifies only two exports from a WASI +application: -- `__wasi_init` - Called after WebAssemembly instantiation but before any other - functions. -- `__wasi_main` - Runs the programs main entry points. May be omitted, for - example, in the case of a library. -- `__wasi_term` - The logical inverse of `__wasi_init`. Optionally called - before module destruction. No other functions within program will be called - after this one. +- `_start` - the program entry point +- `memory` - linear memory used by the program -Linear Memory -------------- +The `_start` start export must be WebAssembly function and will be used as the +program entry point. This is the default name used by `lld` when linking +WebAssembly modules. The embedder is expected to call this function once the +module is instantiated. -All WASI programs are expected to share a linear memory with the embedder. The -memory can either be imported from the embedder or exports to the embedder. If -exported the memory must be named `__wasi_memory`. If imported the import must -be named `memory` from a module names `wasi`. +Many of current WASI unstable APIs require a sharing of linear memory between +the application and the embedder. In order to use any such APIs the WASI module +is expected to export its linear memory under the name `memory`. + +Planned Stable ABI +------------------ + +There is ongoing discussion about what the stable ABI might look like: + +- #13 +- #19 +- #24 From 2b7187f251df3c3de8be5a71c3fd9a1a0ad35c72 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Fri, 31 May 2019 12:05:14 -0700 Subject: [PATCH 3/4] update links --- design/application-abi.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/design/application-abi.md b/design/application-abi.md index 5146ac3b..9aa01dd6 100644 --- a/design/application-abi.md +++ b/design/application-abi.md @@ -32,6 +32,6 @@ Planned Stable ABI There is ongoing discussion about what the stable ABI might look like: -- #13 -- #19 -- #24 +- https://github.com/WebAssembly/WASI/issues/13 +- https://github.com/WebAssembly/WASI/issues/19 +- https://github.com/WebAssembly/WASI/issues/24 From 9ea13085d2ce12f3fcf748ae6cc47fb461d2f615 Mon Sep 17 00:00:00 2001 From: Sam Clegg Date: Thu, 6 Jun 2019 14:55:34 -0700 Subject: [PATCH 4/4] feedback --- design/application-abi.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/design/application-abi.md b/design/application-abi.md index 9aa01dd6..b3156081 100644 --- a/design/application-abi.md +++ b/design/application-abi.md @@ -6,8 +6,8 @@ are also certain expectations that the WASI runtime places on an application that wishes to be portable across WASI implementations. This document describes how a conforming WASI application is expected to behave -in terms of lifecycle (startup, shutdown, etc) and any exports the that -it is expected to include. +in terms of lifecycle (startup, shutdown, etc) and any exports it is expected to +include. Current Unstable ABI -------------------- @@ -18,12 +18,12 @@ application: - `_start` - the program entry point - `memory` - linear memory used by the program -The `_start` start export must be WebAssembly function and will be used as the -program entry point. This is the default name used by `lld` when linking -WebAssembly modules. The embedder is expected to call this function once the -module is instantiated. +The `_start` export must be WebAssembly function and will be used as the program +entry point. This is the default name used by `lld` when linking WebAssembly +modules. The embedder is expected to call this function once the module is +instantiated. -Many of current WASI unstable APIs require a sharing of linear memory between +Many of the current WASI unstable APIs require sharing of linear memory between the application and the embedder. In order to use any such APIs the WASI module is expected to export its linear memory under the name `memory`.