Create Testing.md

.github/workflows/main.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Install Rust (macos)
       run: |
         curl https://sh.rustup.rs | sh -s -- -y
-        echo "##[add-path]$HOME/.cargo/bin"
+        echo "$HOME/.cargo/bin" >> $GITHUB_PATH
       if: matrix.os == 'macos-latest'
     - run: cargo fetch
       working-directory: tools/witx

Charter.md

@@ -11,7 +11,7 @@ the sections of the [CG charter](https://webassembly.github.io/cg-charter/) rela
 
 ## Goals
 
-The mission of this sugbroup is to provide a forum for pre-standardization
+The mission of this subgroup is to provide a forum for pre-standardization
 collaboration on a system interface API for WebAssembly programs.
 
 ## Scope
@@ -21,7 +21,7 @@ The Subgroup will consider topics related to system interface APIs, including:
 - APIs for host filesystems, network stacks, and other resources.
 - APIs for graphics, audio, input devices
 - APIs for encryption, format conversion, and other transformations
-  (particularly where hardware accelleration may be available on some platforms)
+  (particularly where hardware acceleration may be available on some platforms)
 
 
 ## Deliverables

README.md

@@ -1,26 +1,26 @@
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4323447.svg)](https://doi.org/10.5281/zenodo.4323447)
+
 # WebAssembly System Interface
 
 ![WASI](WASI.png)
 
 This repository is for the WebAssembly System Interface (WASI) Subgroup of the
-[WebAssembly Community Group]. Its [Charter] describes the goals, scope and
-deliverables of the group. The repository may contain meeting notes, reports,
-documentation, specifications and/or software produced by the group (although
-larger projects may also have their own repositories).
+[WebAssembly Community Group]. It includes:
+ - [charter]: describes the goals, scope and deliverables of the group
+ - [docs]: learn more about WASI
+ - [meetings]: schedules and agendas for video conference and in-person meetings
+ - [phases]: the current WASI specifications
+ - [proposals]: the status of each new specification proposal
 
+[charter]: Charter.md
+[docs]: docs/README.md
+[meetings]: meetings/README.md
+[phases]: phases/README.md
+[proposals]: docs/Proposals.md
 [WebAssembly Community Group]: https://www.w3.org/community/webassembly/
-[Charter]: Charter.md
 
-We'll be adding more content here before long, but for now, check out these:
- - https://hacks.mozilla.org/2019/03/standardizing-wasi-a-webassembly-system-interface/ - Blog post introducing WASI
- - https://wasi.dev/ - Links to more information about WASI, including
-   how to get started using it.
- - https://github.com/WebAssembly/WASI/issues - This repo's issue tracker
+### Contributing
 
-The issue tracker is the place to ask questions, make suggestions, and start
-discussions.
+The [issue tracker] is the place to ask questions, make suggestions, and start discussions.
 
-Schedules and agendas for video conference and in-person meetings are posted
-[here](meetings/README.md).
-
-API specification proposals are [here](phases/README.md).
+[issue tracker]: https://github.com/WebAssembly/WASI/issues

design/application-abi.md

@@ -1,7 +1,7 @@
 WASI Application ABI
 ====================
 
-In addition to the APIs defined by the various WASI [modules](modules.md) there
+In addition to the APIs defined by the various WASI modules there
 are also certain expectations that the WASI runtime places on an application
 that wishes to be portable across WASI implementations.
 
@@ -15,26 +15,40 @@ Current Unstable ABI
 There are two kinds of modules:
 
  - A *command* exports a function named `_start`, with no arguments and no return
-   values. Environments shall call this function once, after instantiating the
-   module and all of its dependencies. After this function exits, the instance
-   is considered terminated and no further use of any of its exports should be
-   permitted.
+   values.
 
- - A *reactor* exports a function named `_initialize`, with no arguments and no
-   return values. Environments shall call this function once, after instantiating
-   the module and all of its dependencies. After this function exits, the instance
-   remains live, and its exports may be accessed.
+   Command instances may assume that they will be called from the environment
+   at most once. Command instances may assume that none of their exports are
+   accessed outside the duraction of that call.
+
+ - All other modules are *reactors*. A reactor may export a function named
+   `_initialize`, with no arguments and no return values.
+
+   If an `_initialize` export is present, reactor instances may assume that it
+   will be called by the environment at most once, and that none of their
+   other exports are accessed before that call.
+
+   After being instantiated, and after any `_initialize` function is called,
+   a reactor instance remains live, and its exports may be accessed.
 
 These kinds are mutually exclusive; implementations should report an error if
 asked to instantiate a module containing exports which declare it to be of
 multiple kinds.
 
-Regardless of the kind, all programs accessing WASI APIs also export a linear
-memory with the name `memory`. Pointers in WASI API calls are relative to this
-memory's index space.
+Regardless of the kind, all modules accessing WASI APIs also export a linear
+memory with the name `memory`. Data pointers in WASI API calls are relative to
+this memory's index space.
+
+Regardless of the kind, all modules accessing WASI APIs also export a table
+with the name `__indirect_function_table`. Function pointers in WASI API calls
+are relative to this table's index space.
+
+Environments shall not access exports named `__heap_base` or `__data_end`.
+Toolchains are encouraged to avoid providing these exports.
 
 In the future, as the underlying WebAssembly platform offers more features, we
-we hope to eliminate the requirement to export all of linear memory.
+we hope to eliminate the requirement to export all of linear memory or all of
+the indirect function table.
 
 Planned Stable ABI
 ------------------

docs/DesignPrinciples.md

@@ -228,8 +228,8 @@ aligning with them so that we'll be ready when they are.
 As another example, WASI's
 [witx](https://github.com/WebAssembly/WASI/blob/master/docs/witx.md)
 file format is designed to be a
-straightforward superset of the [module type
-proposal](https://github.com/WebAssembly/module-types/blob/master/proposals/module-types/Overview.md)'s
+straightforward superset of the [module linking
+proposal](https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md)'s
 .wit format and the [annotations
 proposal](https://github.com/WebAssembly/annotations/)'s annotation
 syntax.
@@ -243,8 +243,8 @@ transparently. This can be used to adapt or attenuate the functionality
 of a WASI API without changing the code using it.
 
 In WASI, we envision interposition will primarily be configured
-through the mechanisms in the interface types' [linking
-proposal](https://github.com/WebAssembly/interface-types/blob/linking/proposals/interface-types/linking/Explainer.md).
+through the mechanisms in the module linking' [link-time virtualization
+](https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md#link-time-virtualization).
 Imports are resolved when a module is instantiated, which may happen
 during the runtime of a larger logical application, so we can support
 interposition of WASI APIs without defining them in terms of explicit

docs/Proposals.md

@@ -32,6 +32,7 @@ Proposals follow [this process document](https://github.com/WebAssembly/WASI/blo
 | [Clocks][wasi-clocks]                                                          | Dan Gohman                             |
 | [Random][wasi-random]                                                          | Dan Gohman                             |
 | [Misc][wasi-misc]                                                              | Dan Gohman                             |
+| [Machine Learning (wasi-nn)][wasi-nn]                                          | Andrew Brown and Mingqiu Sun           |
 
 ### Phase 1 - Feature Proposal (CG)
 
@@ -49,11 +50,12 @@ Proposals follow [this process document](https://github.com/WebAssembly/WASI/blo
 
 Please see [Contributing to WebAssembly](https://github.com/WebAssembly/WASI/blob/master/Contributing.md) for the most up-to-date information on contributing proposals to standard.
 
-[wasi-io]: https://github.com/WebAssembly/WASI/phases
-[filesystem]: https://github.com/WebAssembly/WASI/phases
-[wasi-command-line]: https://github.com/WebAssembly/WASI/phases
-[clocks]: https://github.com/WebAssembly/WASI/phases
-[random]: https://github.com/WebAssembly/WASI/phases
-[misc]: https://github.com/WebAssembly/WASI/phases
-[wasi-crypto]: https://github.com/WebAssembly/WASI-crypto
-[wasi-proxy-wasm]: https://github.com/WebAssembly/WASI
+[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks
+[wasi-command-line]: https://github.com/WebAssembly/wasi-classic-command
+[wasi-crypto]: https://github.com/WebAssembly/wasi-crypto
+[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem
+[wasi-io]: https://github.com/WebAssembly/wasi-io
+[wasi-misc]: https://github.com/WebAssembly/wasi-misc
+[wasi-nn]: https://github.com/WebAssembly/wasi-nn
+[wasi-proxy-wasm]: https://github.com/proxy-wasm/spec
+[wasi-random]: https://github.com/WebAssembly/wasi-random

docs/README.md

@@ -0,0 +1,15 @@
+# Documentation
+
+WASI documentation includes:
+ - [Overview](WASI-overview.md): provides an introduction to WASI and its history
+ - [Goals](HighLevelGoals.md): a succinct list of WASI's design goals
+ - [Design Principles](DesignPrinciples.md): discusses details on the principles of capability-based security, scope,
+ POSIX/Web, etc.
+ - [WITX](witx.md): an introduction to the WITX specification language
+ - [Process](Process.md): describes how to move a WASI proposal in to the specification
+ - [Proposals](Proposals.md): lists the current WASI proposals by phase
+
+Additionally, here are some links that may be helpful in understanding WASI:
+ - The blog post introducing WASI: [Standardizing WASI: A system interface to run WebAssembly outside the web](https://hacks.mozilla.org/2019/03/standardizing-wasi-a-webassembly-system-interface/)
+ - The [wasi.dev](https://wasi.dev) web site includes links to more information about WASI, including how to get started using it
+ - This repository's [issue tracker](https://github.com/WebAssembly/WASI/issues) 

docs/Testing.md

@@ -0,0 +1,88 @@
+# Testing
+
+A test case takes the form of a binary \<basename\>.wasm file, next to that that there will always be a \<basename\>.\<ext\> source file from which the test was originally compiled from which can be used as a reference in the event of an error.
+
+Additionally, any of the following optional auxilary files and directories may be present:
+
+- \<basename\>.arg
+- \<basename\>.env
+- \<basename\>.dir
+- \<basename\>.stdin
+- \<basename\>.stdout
+- \<basename\>.stderr
+- \<basename\>.status
+
+## Running tests
+
+```bash
+# Usage: $1 <runtime> <path_to_binary.wasm>
+# $1 wasmtime proc_exit-success.wasm
+# $1 wasmer proc_exit-failure.wasm
+#!/usr/bin/env bash
+
+runtime=$1
+input=$2
+
+prefix=${input%.*}
+if [ -e "$prefix.stdin" ]; then
+  stdin="$prefix.stdin"
+else
+  stdin="/dev/null"
+fi
+
+output="$(mktemp -d)"
+stdout_actual="$output/stdout"
+stderr_actual="$output/stderr"
+status_actual="$output/status"
+
+if [ -e "$prefix.arg" ]; then
+  arg=$(cat "$prefix.env")
+else
+  arg=""
+fi
+
+if [ -e "$prefix.env" ]; then
+  env=$(sed -e 's/^/--env /' < "$prefix.env")
+else
+  env=""
+fi
+
+if [ -e "$prefix.dir" ]; then
+  dir="--dir $prefix.dir"
+else
+  dir=""
+fi
+
+status=0
+
+"$runtime" $dir $input -- $arg \
+  < "$stdin" \
+  > "$stdout_actual" \
+  2> "$stderr_actual" \
+  || status=$?
+
+echo $status > "$status_actual"
+
+stdout_expected="$prefix.stdout"
+if [ -e "$stdout_expected" ]; then
+  diff -u "$stderr_expected" "$stderr_actual"
+fi
+
+stderr_expected="$prefix.stderr"
+if [ -e "$stderr_expected" ]; then
+  diff -u "$stdout_expected" "$stdout_actual"
+fi
+
+status_expected="$prefix.status"
+if [ -e "$prefix.status" ]; then
+  diff -u "$status_expected" "$status_actual"
+elif [ ! "$status" -eq "0" ]; then
+  cat $stderr_actual
+  exit 1
+fi
+```
+
+## Writing tests
+
+- Use the following naming convention of \<system_call\>[-\<variant\>].<ext>.
+- Scope tests to the smallest unit possible.

docs/witx.md

@@ -1,7 +1,7 @@
 # Know your `witx`
 
 The `witx` file format is an experimental format which is based on the
-[module types] text format (`wit`), (which is in turn based on the
+[module linking] text format (`wit`), (which is in turn based on the
 [wat format], which is based on [S-expressions]). It adds some features
 using the same syntax as [interface types], some features with syntax
 similar to [gc types], as well as a few special features of its own.
@@ -22,7 +22,7 @@ the goals here are to remain aligned with interface types and other relevant
 WebAssembly standards and proposals wherever practical, and to be an input 
 into the design process of interface types.
 
-[module types]: https://github.com/WebAssembly/module-types/blob/master/proposals/module-types/Overview.md
+[module linking]: https://github.com/WebAssembly/module-linking/blob/master/proposals/module-linking/Explainer.md
 [interface types]: https://github.com/WebAssembly/interface-types/blob/master/proposals/interface-types/Explainer.md
 [gc types]: https://github.com/WebAssembly/gc
 [wat format]: https://webassembly.github.io/spec/core/bikeshed/index.html#text-format%E2%91%A0

meetings/2020/WASI-04-09.md

@@ -33,3 +33,51 @@ Installation is required, see the calendar invite.
         1. Discussion: Next steps.
 
 ## Meeting Notes
+
+Agenda: https://github.com/WebAssembly/WASI/blob/master/meetings/2020/WASI-04-09.md
+
+Attendees:
+
+Dan Gohman
+Lee Campbell
+Yury Delendik
+Jacob Mischka
+Andrew Brown
+Mark McCaskey
+Matthew Fisher
+Radu Matei
+Piotr Sikora
+Pat Hickey
+Benjamin Brittain
+Johnnie Birch
+
+Meeting notes:
+Moving to a CG-style phases process: https://github.com/WebAssembly/WASI/pull/252
+LC: What should be the expectations for wasi-sdk and/or other toolchains when a feature is stabilized?
+DG: witx support will help wasi-sdk, Rust, and others adopt to new APIs
+PH: witx is written in Rust, we’re happy for people to implement it in other languages as well. Currently it just emits markdown docs. Wasi-libc has a C header generator.
+LC: witx becomes the ABI standard, “bytes on the wire”. Clients may have higher-level abstractions. The ABI is where the stability is. Applications may link against different versions of higher-level abstraction layers, but as long as the ABI layer is stable they can run on ABI-conforming implementations.
+
+
+Proxy-wasm
+Vote: approve for Phase 1 (see previous item)?
+Result - approved, unanimous
+
+Discussion: Next steps.
+Piotr to split out pieces of the spec which can be considered independently.
+
+Discussion: Threads in APIs
+https://github.com/WebAssembly/threads/issues/138
+LC: It’d be nice to start thinking about thread safety and which APIs are thread-safe.
+BB: Function signatures are typically not sufficient to know if something is thread-safe.
+LW: The “is shared” predicate needs to be propagated through APIs. Everything is unshared by default. We need a shared attribute for tables, etc., and we’d need to have the shared attribute on functions to make them shared.
+Without the shared attribute, functions can only be called from one thread.
+The shared attribute for functions would need to be added in the core wasm spec, and then witx, being based on core wasm, would inherit it.
+LW: Part of adding threading support sufficient for WASI would require adding a thread-local storage mechanism.
+
+Discussion: mmap
+LC: What is the short-term plan for mmap?
+DG: On the web, mmap is complicated by web compat. But WASI can pursue this.
+LW: FWIW, https://github.com/WebAssembly/design/blob/master/FutureFeatures.md#finer-grained-control-over-memory is a long-standing thing we’ve said we’ve wanted in the wasm CG, but maybe it’s better solved by WASI
+
+LW: I can put together a proposal for a platform-independent mmap interface.