From fe888e1ae7a0647a692b6dc3f6b0be5b06dc8d06 Mon Sep 17 00:00:00 2001 From: Luke Wagner Date: Wed, 10 Jun 2015 15:09:05 -0500 Subject: Update URL of polyfill repo to polyfill-prototype-1 --- BinaryEncoding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index d2f8fca..00d0cc9 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -43,14 +43,14 @@ Yes: * Large reductions in payload size can still significantly decrease the compressed file size. * Experimental results from a - [polyfill prototype](https://github.com/WebAssembly/polyfill) show the + [polyfill prototype](https://github.com/WebAssembly/polyfill-prototype-1) show the gzipped binary format to be about 20-30% smaller than the corresponding gzipped asm.js. * A binary format that represents the names of variables and functions with raw indices instead of strings is much faster to decode: array indexing vs. dictionary lookup. * Experimental results from a - [polyfill prototype](https://github.com/WebAssembly/polyfill) show that + [polyfill prototype](https://github.com/WebAssembly/polyfill-prototype-1) show that decoding the binary format is about 23× faster than parsing the corresponding asm.js source (using [this demo](https://github.com/lukewagner/AngryBotsPacked), comparing -- cgit v1.2.3 From 95b607450bdeeac671e7f0d4eba7cbfacedd21cb Mon Sep 17 00:00:00 2001 From: Luke Wagner Date: Wed, 10 Jun 2015 15:48:59 -0500 Subject: Update URLs to account for spec->design repo renaming --- AstSemantics.md | 2 +- BinaryEncoding.md | 2 +- FAQ.md | 3 +-- FeatureTest.md | 2 +- 4 files changed, 4 insertions(+), 5 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/AstSemantics.md b/AstSemantics.md index c7a703e..8e6a9bd 100644 --- a/AstSemantics.md +++ b/AstSemantics.md @@ -130,7 +130,7 @@ which leads to the following advantages: splitting, which can reduce throughput overhead, at the cost of increasing code size (potentially very significantly in pathological cases). * The - [signature-restricted proper tail-call](https://github.com/WebAssembly/spec/blob/master/EssentialPostMVPFeatures.md#signature-restricted-proper-tail-calls) + [signature-restricted proper tail-call](EssentialPostMVPFeatures.md#signature-restricted-proper-tail-calls) feature would allow efficient compilation of arbitrary irreducible control flow. diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 00d0cc9..97a143f 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -18,7 +18,7 @@ Reducing download size, is achieved through three layers: * We can do better than generic compression because we are aware of the AST structure and other details: * For example, macro compression that - [deduplicates AST trees](https://github.com/WebAssembly/spec/issues/58#issuecomment-101863032) + [deduplicates AST trees](https://github.com/WebAssembly/design/issues/58#issuecomment-101863032) can focus on AST nodes + their children, thus having `O(nodes)` entities to worry about, compared to generic compression which in principle would need to look at `O(bytes*bytes)` entities. Such macros would allow the diff --git a/FAQ.md b/FAQ.md index 6653daa..4b1fba0 100644 --- a/FAQ.md +++ b/FAQ.md @@ -89,8 +89,7 @@ learning and teaching purposes. In fact, by dropping all the [coercions required validation](http://asmjs.org/spec/latest/#introduction), the WebAssembly text format should be much more natural to read and write than asm.js. Outside the browser, command-line and online tools that convert between text and binary will also be made readily available. Lastly, a scalable form of -source maps is also being considered as part of the WebAssembly [tooling story] -(https://github.com/WebAssembly/spec/blob/master/Tooling.md). +source maps is also being considered as part of the WebAssembly [tooling story](Tooling.md). ## What's the story for Emscripten users? diff --git a/FeatureTest.md b/FeatureTest.md index f9877dc..cd6ca34 100644 --- a/FeatureTest.md +++ b/FeatureTest.md @@ -8,4 +8,4 @@ Feature tests will be available from WebAssembly itself, as well as from JavaScript. Details -[are still be hashed out](https://github.com/WebAssembly/spec/issues/90). +[are still be hashed out](https://github.com/WebAssembly/design/issues/90). -- cgit v1.2.3 From e47c672a80a2e159e1b01779f33062894e62d85b Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Fri, 12 Jun 2015 14:39:36 +0200 Subject: Short document name bikeshed. --- AstSemantics.md | 6 ++-- BinaryEncoding.md | 5 ++-- EssentialPostMVPFeatures.md | 70 --------------------------------------------- FutureFeatures.md | 8 +++--- HighLevelGoals.md | 4 +-- MVP.md | 8 +++--- Nondeterminism.md | 10 +++---- PostMVP.md | 70 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- Web.md | 9 +++--- 10 files changed, 96 insertions(+), 96 deletions(-) delete mode 100644 EssentialPostMVPFeatures.md create mode 100644 PostMVP.md (limited to 'BinaryEncoding.md') diff --git a/AstSemantics.md b/AstSemantics.md index 05d2092..f295559 100644 --- a/AstSemantics.md +++ b/AstSemantics.md @@ -130,7 +130,7 @@ which leads to the following advantages: splitting, which can reduce throughput overhead, at the cost of increasing code size (potentially very significantly in pathological cases). * The - [signature-restricted proper tail-call](EssentialPostMVPFeatures.md#signature-restricted-proper-tail-calls) + [signature-restricted proper tail-call](PostMVP.md#signature-restricted-proper-tail-calls) feature would allow efficient compilation of arbitrary irreducible control flow. @@ -158,12 +158,12 @@ to easily be folded into the hardware load instruction *and* for groups of loads with the same base and different offsets to easily share a single bounds check. In the MVP, the indices are 32-bit unsigned integers. With -[64-bit integers](EssentialPostMVPFeatures.md#64-bit-integers) and +[64-bit integers](PostMVP.md#64-bit-integers) and [>4GiB heaps](FutureFeatures.md#heaps-bigger-than-4gib), these nodes would also accept 64-bit unsigned integers. In the MVP, heaps are not shared between threads. When -[threads](EssentialPostMVPFeatures.md#threads) are added as a feature, the basic +[threads](PostMVP.md#threads) are added as a feature, the basic `LoadHeap`/`StoreHeap` nodes will have the most relaxed semantics specified in the memory model and new heap-access nodes will be added with atomic and ordering guarantees. diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 97a143f..3aad2a6 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -123,8 +123,9 @@ conflict-avoidance practices surrounding string names: * To avoid (over time) large index-space declaration sections that are largely the same between modules, finalized versions of standards would define named baseline index spaces that modules could optionally use as a starting point to further refine. - * For example, to use all of [the MVP](MVP.md) plus [SIMD](EssentialPostMVPFeatures.md#fixed-width-simd) - the declaration could be "base" followed by the list of SIMD opcodes used. + * For example, to use all of [the MVP](MVP.md) plus + [SIMD](PostMVP.md#fixed-width-simd) the declaration could be "base" + followed by the list of SIMD opcodes used. * This feature would also be most useful for people handwriting the [text format](TextFormat.md). * However, such a version declaration does not establish a global "version" for the module or affect anything outside of the initialization of the index spaces; decoders would diff --git a/EssentialPostMVPFeatures.md b/EssentialPostMVPFeatures.md deleted file mode 100644 index 9d4347f..0000000 --- a/EssentialPostMVPFeatures.md +++ /dev/null @@ -1,70 +0,0 @@ -# Essential Post-MVP Features - -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 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 - -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 - -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/FutureFeatures.md b/FutureFeatures.md index dbadd13..dd4a33c 100644 --- a/FutureFeatures.md +++ b/FutureFeatures.md @@ -2,10 +2,10 @@ These are features that make sense in the context of the [high-level goals](HighLevelGoals.md) of WebAssembly but are not considered part -of the [Minimum Viable Product](MVP.md) or the -[essential post-MVP feature set](EssentialPostMVPFeatures.md) which are expected -to be standardized immediately after the MVP. These will be prioritized based on -developer feedback, and will be available under [feature tests](FeatureTest.md). +of the [Minimum Viable Product](MVP.md) or the essential [post-MVP](PostMVP.md) +feature set which are expected to be standardized immediately after the +MVP. These will be prioritized based on developer feedback, and will be +available under [feature tests](FeatureTest.md). ## Great tooling support diff --git a/HighLevelGoals.md b/HighLevelGoals.md index 57d36ce..bd23ea7 100644 --- a/HighLevelGoals.md +++ b/HighLevelGoals.md @@ -12,8 +12,8 @@ * ship an effective and efficient [polyfill](Polyfill.md) library for the MVP that translates WebAssembly code into JavaScript in the client so that WebAssembly MVP can run on existing browsers; - * ship a follow-up to the MVP which adds several more - [essential features](EssentialPostMVPFeatures.md); and + * ship a [follow-up to the MVP](PostMVP.md) which adds several more + essential features; and * continue to iteratively specify [additional features](FutureFeatures.md), prioritized by feedback and experience, including support for languages other than C/C++. diff --git a/MVP.md b/MVP.md index 4d557d1..e800528 100644 --- a/MVP.md +++ b/MVP.md @@ -3,10 +3,10 @@ As stated in the [high-level goals](HighLevelGoals.md), the first release aims at being a Minimum Viable Product (MVP). This means that there are important features we *know* we want and need, but are post-MVP; these are in a separate -[essential post-MVP features doc](EssentialPostMVPFeatures.md). The MVP will -contain features which are available today in modern web browsers and which -perform well even on mobile devices, which leads to roughly the same -functionality as [asm.js](http://asmjs.org). +essential [post-MVP](PostMVP.md) features document. The MVP will contain +features which are available today in modern web browsers and which perform well +even on mobile devices, which leads to roughly the same functionality as +[asm.js](http://asmjs.org). This document explains the contents of the MVP at a high-level. There are also separate docs with more precise descriptions of: diff --git a/Nondeterminism.md b/Nondeterminism.md index 308861d..d6693ca 100644 --- a/Nondeterminism.md +++ b/Nondeterminism.md @@ -25,16 +25,16 @@ 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. + - [When threads are added as a feature](PostMVP.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) + - [Fixed-width SIMD may want some flexibility](PostMVP.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. diff --git a/PostMVP.md b/PostMVP.md new file mode 100644 index 0000000..9d4347f --- /dev/null +++ b/PostMVP.md @@ -0,0 +1,70 @@ +# Essential Post-MVP Features + +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 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 + +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 + +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/README.md b/README.md index ad79830..9d132a2 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ followed by the [FAQ](FAQ.md). We've mapped out features we expect to ship: 1. In [the Minimum Viable Product (MVP)](MVP.md); - 2. Closely [after the MVP](EssentialPostMVPFeatures.md); + 2. Closely [after the MVP](PostMVP.md); 3. In [future versions](FutureFeatures.md). Join us: diff --git a/Web.md b/Web.md index e1f2513..f64e5cd 100644 --- a/Web.md +++ b/Web.md @@ -33,14 +33,13 @@ that the design, especially that of the [MVP](MVP.md), are sensible: 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()`. +* Once [threads are supported](PostMVP.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: +* Once [SIMD is supported](PostMVP.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). -- cgit v1.2.3