Merge branch 'master' into generate

9 files changed, 195 insertions, 81 deletions

diff --git a/EssentialPostMVPFeatures.md b/EssentialPostMVPFeatures.md
index aea0a35..9d4347f 100644
--- a/EssentialPostMVPFeatures.md
+++ b/EssentialPostMVPFeatures.md
@@ -1,47 +1,70 @@
 # Essential Post-MVP Features
 
-This is a list of essential features that are known to be needed ASAP, but were
-removed from [the MVP](MVP.md) since there was not (yet) a portably-efficient
-polyfill via JavaScript. There is a much bigger
-[list of features](FutureFeatures.md) that will be added after this list,
-prioritized by feedback and experience. These features will be available under
-[feature tests](FeatureTest.md).
+Some features are know to be essential and needed as soon as possible but aren't
+in the [Minimum Viable Product (MVP)](MVP.md) because there isn't yet a
+portably-efficient [polyfill](Polyfill.md) via JavaScript. There is a much
+bigger [list of features](FutureFeatures.md) that will be added after these
+essential features.
+
+Post-MVP features will be available under [feature tests](FeatureTest.md).
 
 ## Threads
-* Provide low-level buildings blocks for pthreads-style shared memory: shared memory,
-  atomics + futexes (or [synchronics](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4195.pdf)).
-* Import [SharedArrayBuffer proposal](https://docs.google.com/document/d/1NDGA_gZJ7M7w1Bh8S0AoDyEqwDdRh4uSoTPSNn77PFk).
-  * The goal is to reuse the specification of memory model, happens-before, etc (with TC39) and backend implementation
-    (same IR nodes and semantic invariants preserved).
-* Modules can have global variables that are either shared or thread-local.
-  * While the heap could be used for shared global variables, global variables are not aliasable
-    and thus allow more aggressive optimization.
-* Initially, a WebAssembly module is distributed between workers via `postMessage()`.
-  * This also has the effect of explicitly sharing code so that engines don't
-    perform N fetches and compile N copies.
-  * May later standardize a more direct way to create a thread from WebAssembly.
+
+Provide low-level buildings blocks for pthreads-style shared memory: shared
+memory between threads, atomics and futexes (or [synchronic][]). WebAssembly's
+approach would be similar to the [original PNaCl atomic support][] and
+[SharedArrayBuffer][] proposal: reuse the specification of memory model,
+happens-before relationship, and synchronize-with edges as defined in other
+languages.
+
+Modules can have global variables that are either shared or thread-local. While
+the heap could be used for shared global variables, global variables are not
+aliasable and thus allow more aggressive optimization.
+
+  [synchronic]: http://wg21.link/n4195
+  [original PNaCl atomic support]: https://developer.chrome.com/native-client/reference/pnacl-c-cpp-language-support#memory-model-and-atomics
+  [SharedArrayBuffer]: https://docs.google.com/document/d/1NDGA_gZJ7M7w1Bh8S0AoDyEqwDdRh4uSoTPSNn77PFk
 
 ## Fixed-width SIMD
-* Essentially, import [SIMD.js](https://github.com/johnmccutchan/ecmascript_simd).
-  * Would be statically typed analogous to [SIMD.js-in-asm.js](http://discourse.specifiction.org/t/request-for-comments-simd-js-in-asm-js).
-  * The goal is to both reuse specification of op semantics (with TC39) and backend implementation (same IR nodes)
-  * Track SIMD.js after the MVP.
-* SIMD adds new primitive variable/expression types (e.g., `float32x4`) so it has to be part of
-  the core semantics.
-* SIMD operations (e.g., `float32x4.add`) could be either builtin ops (no different than int32 add) or
-  exports of a builtin SIMD module.
-
-## 64-bit integers
-* Provide access to efficient 64-bit arithmetic.
-* Some code will want to only use 64-bit integers when running on a 64-bit system (for performance
-  reasons) so provide a "has native 64-bit integer" query.
+
+Support fixed-width SIMD vectors, initially only for 128-bit wide vectors as
+demonstrated in [PNaCl's SIMD][] and [SIMD.js][].
+
+SIMD adds new primitive variable and expression types (e.g., `float32x4`) so it
+has to be part of the core semantics. SIMD operations (e.g., `float32x4.add`)
+could be either builtin operations (no different from `int32.add`) or exports of
+a builtin SIMD module.
+
+  [PNaCl's SIMD]: https://developer.chrome.com/native-client/reference/pnacl-c-cpp-language-support#portable-simd-vectors
+  [SIMD.js]: https://github.com/johnmccutchan/ecmascript_simd
 
 ## Zero-cost Exception Handling
-* Developer access to stack unwinding and inspection.
-* This may be used to implement `setjmp`/`longjmp` (instead of the usual
-  opposite approach). This can enable all of the defined behavior of
-  `setjmp`/`longjmp`, namely unwinding the stack, but does not allow
-  the undefined behavior case of jumping forward to a stack that
-  was already unwound (which is sometimes used to implement coroutines;
-  however, explicit coroutine support is being considered separately
-  anyhow).
+
+The WebAssembly MVP (compilers and polyfills) may support four no-exception
+modes for C++:
+* Compiler transforms `throw` to `abort()`.
+* Compiler-enforced `-fno-exceptions` mode (note [caveats][]).
+* Compiler conversion of exceptions to branching at all callsites.
+* In a Web environment exception handling can be emulated using JavaScript
+  exception handling, which can provide correct semantics but isn't fast.
+
+These modes are suboptimal for code bases which rely on C++ exception handling,
+but are perfectly acceptable for C code, or for C++ code which avoids
+exceptions. This doesn't prevent developers from using the C++ standard library:
+their code will function correctly (albeit slower at times) as long as it
+doesn't encounter exceptional cases.
+
+Post-MVP, WebAssembly will gain support for developer access to stack unwinding,
+inspection, and limited manipulation. These are critical to supporting zero-cost
+exception handling by exposing [low-level capabilities][].
+
+In turn, stack unwinding, inspection, and limited manipulation will be used to
+implement `setjmp`/`longjmp`. This can enable all of the defined behavior of
+`setjmp`/`longjmp`, namely unwinding the stack without calling C++
+destructors. It does not, however, allow the undefined behavior case of jumping
+forward to a stack that was already unwound which is sometimes used to implement
+coroutines. Coroutine support is being
+[considered separately](FutureFeatures.md#Coroutines).
+
+  [caveats]: https://blog.mozilla.org/nnethercote/2011/01/18/the-dangers-of-fno-exceptions
+  [low-level capabilities]: https://extensiblewebmanifesto.org
diff --git a/FAQ.md b/FAQ.md
index 4b1fba0..d2be3a3 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -1,5 +1,9 @@
 # FAQ
 
+## What are WebAssembly's use cases?
+
+WebAssembly was designed with [a variety of use cases in mind](UseCases.md).
+
 ## Can the polyfill really be efficient?
 
 Yes, this is a [high-level goal](HighLevelGoals.md) and there is a 
diff --git a/FutureFeatures.md b/FutureFeatures.md
index 7021668..dbadd13 100644
--- a/FutureFeatures.md
+++ b/FutureFeatures.md
@@ -89,6 +89,13 @@ implementation running on such a platform may restrict allocations to the lower
 * Text source maps become intractably large for even moderate-sized compiled
   codes, so probably need to define new binary format for source maps.
 
+## Coroutines
+
+Coroutines will [eventually be part of C++][] and is already popular in other
+programming languages that WebAssembly will support.
+
+  [eventually be part of C++]: http://wg21.link/n4499
+
 ## Signature-restricted Proper Tail Calls
 
 See the [asm.js RFC][] for a full description of signature-restricted Proper
diff --git a/IncompletelySpecifiedBehavior.md b/IncompletelySpecifiedBehavior.md
deleted file mode 100644
index d525051..0000000
--- a/IncompletelySpecifiedBehavior.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Incompletely Specified Behavior
-
-WebAssembly is a [portable](Portability.md) sandboxed platform. Applications
-can't access data outside the sandbox without going through appropriate APIs, or
-otherwise escape the sandbox, even if the behavior inside the sandbox should
-ever be unspecified in any way.
-
-WebAssembly always maintains valid callstacks. Return addresses are stored on the trusted stack and can't be clobbered by the application. And, WebAssembly ensures that calls and branches always have valid destinations.
-
-Beyond that, WebAssembly minimizes observable differences between implementations, to reduce the risk of applications becoming dependent on any particular implementation's behavior. However, occasionally compromises are made due to performance concerns, listed below.
-
-In particular, WebAssembly has no [nasal demons](https://en.wikipedia.org/w/index.php?title=Nasal_demons), since they are an extreme on the spectrum of observable differences, and since they make it difficult to reason about what state an application might be in. WebAssembly prefers to [trap](AstSemantics.md) when feasible, and otherwise it permits a specific set of possible conforming behaviors.
-
-The following is a list of the places where the WebAssembly specification currently admits or is expected to admit multiple possible behaviors.
-
- - [Out of bounds heap accesses](AstSemantics.md#accessing-the-heap)
-
- - [Environment-dependent resource limits may be exhausted](AstSemantics.md)
-
- - [NaN bit patterns](AstSemantics.md#floating-point-operations)
-
- - [Races between threads](EssentialPostMVPFeatures.md#threads)
-
- - [Fixed-width SIMD may want some flexibility](EssentialPostMVPFeatures.md#fixed-width-simd)
-   - In SIMD.js, floating point values may or may not have subnormals flushed to zero.
-   - In SIMD.js, operations ending in "Approximation" return approximations that may vary between platforms.
-
-## Note for users of C, C++, and similar languages
-
-Some operations which have fully defined behavior in WebAssembly itself may nonetheless have undefined behavior at the source code level. For example, while unaligned memory access is fully defined in WebAssembly, C and C++ compilers make no guarantee that a (non-packed) unaligned memory access at the source level is harmlessly translated into an unaligned memory access in WebAssembly. And in practice, popular C and C++ compilers do optimize on the assumption that alignment rules are followed, meaning that they don't always preserve program behavior otherwise.
-
-On WebAssembly, the primary invariants are always maintained. Demons can't actually fly out your nose, as that would constitute an escape from the sandbox. And, callstacks can't become corrupted.
-
-Other than that, programs which invoke undefined behavior at the source language level may be compiled into WebAssembly programs which do anything else, including corrupting the contents of the application heap, calling APIs with arbitrary parameters, hanging, trapping, or consuming arbitrary amounts of resources (within the limits).
-
-[Tools are being developed and ported](Tooling.md) to help developers find and fix bugs in their code.
diff --git a/Nondeterminism.md b/Nondeterminism.md
new file mode 100644
index 0000000..308861d
--- /dev/null
+++ b/Nondeterminism.md
@@ -0,0 +1,51 @@
+# Nondeterminism in WebAssembly
+
+WebAssembly is a [portable](Portability.md) sandboxed platform with limited,
+local, nondeterminism. 
+  * *Limited*: non-deterministic execution can only occur in a small number of
+    well-defined cases (described below) and, in those cases, the implementation
+    may select from a limited set of possible behaviors.
+  * *Local*: when non-deterministic execution occurs, the effect is local,
+    there is no "spooky action at a distance".
+
+The limited, local, non-deterministic model implies:
+  * Applications can't access data outside the sandbox without going through
+    appropriate APIs, or otherwise escape the sandbox.
+  * WebAssembly always maintains valid, trusted callstacks; stray pointer writes
+    cannot corrupt return addresses or spilled variables on the stack.
+  * Calls and branches always have valid destinations ensuring 
+    [Control Flow Integrity](http://research.microsoft.com/apps/pubs/default.aspx?id=64250).
+  * WebAssembly has no [nasal demons](https://en.wikipedia.org/w/index.php?title=Nasal_demons).
+
+Ideally, WebAssembly would be fully deterministic (except where nondeterminism
+was essential to the API, like random number generators, date/time functions or
+input events). Nondeterminism is only specified as a compromise when there is no
+other practical way to achieve [portable](Portability.md) native performance.
+
+The following is a list of the places where the WebAssembly specification
+currently admits nondeterminism:
+
+ - [When threads are added as a feature](EssentialPostMVPFeatures.md#threads),
+   even without shared memory, nondeterminism will be visible through the
+   global sequence of API calls. With shared memory, the result of load
+   operations is nondeterministic.
+
+ - [Out of bounds heap accesses *may* want some flexibility](AstSemantics.md#out-of-bounds)
+
+ - [NaN bit patterns](AstSemantics.md#floating-point-operations)
+
+ - [Fixed-width SIMD may want some flexibility](EssentialPostMVPFeatures.md#fixed-width-simd)
+   - In SIMD.js, floating point values may or may not have subnormals flushed to zero.
+   - In SIMD.js, operations ending in "Approximation" return approximations that may vary between platforms.
+
+ - Environment-dependent resource limits may be exhausted.
+
+## Note for users of C, C++, and similar languages
+
+Some operations which have fully defined behavior in WebAssembly itself may nonetheless have undefined behavior at the source code level. For example, while unaligned memory access is fully defined in WebAssembly, C and C++ compilers make no guarantee that a (non-packed) unaligned memory access at the source level is harmlessly translated into an unaligned memory access in WebAssembly. And in practice, popular C and C++ compilers do optimize on the assumption that alignment rules are followed, meaning that they don't always preserve program behavior otherwise.
+
+On WebAssembly, the primary invariants are always maintained. Demons can't actually fly out your nose, as that would constitute an escape from the sandbox. And, callstacks can't become corrupted.
+
+Other than that, programs which invoke undefined behavior at the source language level may be compiled into WebAssembly programs which do anything else, including corrupting the contents of the application heap, calling APIs with arbitrary parameters, hanging, trapping, or consuming arbitrary amounts of resources (within the limits).
+
+[Tools are being developed and ported](Tooling.md) to help developers find and fix bugs in their code.
diff --git a/Portability.md b/Portability.md
index 031c4ed..2d6991a 100644
--- a/Portability.md
+++ b/Portability.md
@@ -5,7 +5,7 @@ efficiently on a variety of operating systems and instruction set architectures,
 [on the Web](Web.md) and [off the Web](NonWeb.md).
 
 Execution environments which, despite
-[allowed implementation variants](IncompletelySpecifiedBehavior.md), don't offer
+[limited, local, non-determinism](Nondeterminism.md), don't offer
 the following characteristics may be able to execute WebAssembly modules
 nonetheless. In some cases they may have to emulate behavior that the host
 hardware or operating system don't offer so that WebAssembly modules execute
diff --git a/TextFormat.md b/TextFormat.md
index 0a64157..bebd120 100644
--- a/TextFormat.md
+++ b/TextFormat.md
@@ -17,7 +17,7 @@ The text format will be standardized, but only for tooling purposes:
   implement WebAssembly semantics.
 
 Given that the code representation is actually an
-[Abstract Syntax Tree](ASTSemantics.md), the syntax would contain nested
+[Abstract Syntax Tree](AstSemantics.md), the syntax would contain nested
 statements and expressions (instead of the linear list of instructions most
 assembly languages have).
 
diff --git a/UseCases.md b/UseCases.md
new file mode 100644
index 0000000..405cafa
--- /dev/null
+++ b/UseCases.md
@@ -0,0 +1,52 @@
+# Use Cases
+
+WebAssembly's [high-level goals](HighLevelGoals.md) define *what* WebAssembly
+aims to achieve, and in *which order*. *How* WebAssembly achieves its goals is
+documented for [Web](Web.md) and [non-Web](NonWeb.md) platforms. The following
+is an unordered and incomplete list of applications/domains/computations that
+would benefit from WebAssembly and are being considered as use cases during the
+design of WebAssembly.
+
+## Inside the browser
+
+* Better execution for languages and toolkits that are currently cross-compiled
+  to the Web (C/C++, GWT, …).
+* Image / video editing.
+* Games:
+  - Casual games that need to start quickly.
+  - AAA games that have heavy assets.
+  - Game portals (mixed-party/origin content).
+* Peer-to-peer applications (games, collaborative editing, decentralized and
+  centralized).
+* Music applications (streaming, caching).
+* Image recognition.
+* Live video augmentation (e.g. putting hats on people's heads).
+* VR and augmented reality (very low latency).
+* CAD applications.
+* Scientific visualization and simulation.
+* Interactive educational software, and news articles.
+* Platform simulation / emulation (ARC, DOSBox, QEMU, MAME, …).
+* Language interpreters and virtual machines.
+* POSIX user-space environment, allowing porting of existing POSIX applications.
+* Developer tooling (editors, compilers, debuggers, …).
+* Remote desktop.
+* VPN.
+* Encryption.
+* Local web server.
+* Common NPAPI users, within the web's security model and APIs.
+* Fat client for enterprise applications (e.g. databases).
+
+# Outside the browser
+
+* Game distribution service (portable and secure).
+* Server-side compute of untrusted code.
+* Server-side application.
+* Hybrid native apps on mobile devices.
+
+# How WebAssembly can be used
+
+* Entire code base in Web Assembly.
+* Main frame in Web Assembly, but the UI is in JavaScript / HTML.
+* Re-use existing code by targeting Web Assembly, embedded in a larger
+  JavaScript / HTML application. This could be anything from simple helper
+  libraries, to compute-oriented task offload.
diff --git a/Web.md b/Web.md
index ac24b21..e1f2513 100644
--- a/Web.md
+++ b/Web.md
@@ -20,20 +20,33 @@ that the design, especially that of the [MVP](MVP.md), are sensible:
 * A [module](MVP.md#Modules) can be loaded in the same way as an ES6 module
   (`import` statements, `Reflect` API, `Worker` constructor, etc) and the result
   is reflected to JS as an ES6 module object.
-  * Exports are the ES6 module object exports.
-  * An import first passes the module name to the [module loader pipeline][] and
+  - Exports are the ES6 module object exports.
+  - An import first passes the module name to the [module loader pipeline][] and
     resulting ES6 module (which could be implemented in JS or WebAssembly) is
     queried for the export name.
-  * There is no special case for when one WebAssembly module imports another:
+  - There is no special case for when one WebAssembly module imports another:
     they have separate [heaps](MVP.md#heap) and pointers cannot be passed
     between the two. Module imports encapsulate the importer and
     importee. [Dynamic linking](FutureFeatures.md#dynamic-linking) should be
     used to share heaps and pointers across modules.
-  * To synchronously call into JavaScript from C++, the C++ code would declare
+  - To synchronously call into JavaScript from C++, the C++ code would declare
     and call an undefined `extern` function and the target JavaScript function
     would be given the (mangled) name of the `extern` and put inside the
     imported ES6 module.
+* Once [threads are supported](EssentialPostMVPFeatures.md#Threads), a
+  WebAssembly module would initially be distributed between workers via
+  `postMessage()`.
+  - This also has the effect of explicitly sharing code so that engines don't
+    perform N fetches and compile N copies.
+  - May later standardize a more direct way to create a thread from WebAssembly.
+* Once [SIMD is supported](EssentialPostMVPFeatures.md#Fixed-width-SIMD), a Web
+  implementation of WebAssembly would:
+  - Be statically typed analogous to [SIMD.js-in-asm.js][];
+  - Reuse specification of operation semantics (with TC39);
+  - Reuse backend implementation (same IR nodes).
 
   [CORS]: http://www.w3.org/TR/cors/
   [subresource integrity]: http://www.w3.org/TR/SRI/
   [module loader pipeline]: http://whatwg.github.io/loader
+  [SIMD.js-in-asm.js]: http://discourse.specifiction.org/t/request-for-comments-simd-js-in-asm-js
+