Tagging future features with icon. (WebAssembly#839)

Added brief item on multiple return.

Author: flagxor

BinaryEncoding.md

@@ -6,17 +6,19 @@ The binary encoding is a dense representation of module information that enables
 small files, fast decoding, and reduced memory usage.
 See the [rationale document](Rationale.md#why-a-binary-encoding) for more detail.
 
+[:unicorn:][future general] = Planned [future](PostMVP.md) feature
+
 The encoding is split into three layers:
 
 * **Layer 0** is a simple binary encoding of the bytecode instructions and related data structures.
   The encoding is dense and trivial to interact with, making it suitable for
   scenarios like JIT, instrumentation tools, and debugging.
-* **Layer 1** provides structural compression on top of layer 0, exploiting
+* **Layer 1** [:unicorn:][future compression] provides structural compression on top of layer 0, exploiting
   specific knowledge about the nature of the syntax tree and its nodes.
   The structural compression introduces more efficient encoding of values, 
   rearranges values within the module, and prunes structurally identical
   tree nodes.
-* **Layer 2** Layer 2 applies generic compression algorithms, like [gzip](http://www.gzip.org/) and [Brotli](https://datatracker.ietf.org/doc/draft-alakuijala-brotli/), that are already available in browsers and other tooling.
+* **Layer 2** [:unicorn:][future compression] Layer 2 applies generic compression algorithms, like [gzip](http://www.gzip.org/) and [Brotli](https://datatracker.ietf.org/doc/draft-alakuijala-brotli/), that are already available in browsers and other tooling.
 
 Most importantly, the layering approach allows development and standardization to
 occur incrementally. For example, Layer 1 and Layer 2 encoding techniques can be
@@ -25,7 +27,7 @@ compression techniques  stabilize, they can be standardized and moved into nativ
 implementations.
 
 See
-[proposed layer 1 compression](https://github.com/WebAssembly/decompressor-prototype/blob/master/CompressionLayer1.md)
+[proposed layer 1 compression :unicorn:][future compression]
 for a proposal for layer 1 structural compression.
 
 
@@ -67,7 +69,7 @@ All types are distinguished by a negative `varint7` values that is the first byt
 
 Some of these will be followed by additional fields, see below.
 
-Note: Gaps are reserved for future extensions. The use of a signed scheme is so that types can coexist in a single space with (positive) indices into the type section, which may be relevant for future extensions of the type system.
+Note: Gaps are reserved for [future :unicorn:][future general] extensions. The use of a signed scheme is so that types can coexist in a single space with (positive) indices into the type section, which may be relevant for future extensions of the type system.
 
 ### `value_type`
 A `varint7` indicating a [value type](Semantics.md#types). One of:
@@ -92,7 +94,7 @@ In the MVP, only one type is available:
 
 * [`anyfunc`](AstSemantics.md#table)
 
-Note: In the future, other element types may be allowed.
+Note: In the [future :unicorn:][future general], other element types may be allowed.
 
 ### `func_type`
 The description of a function signature. Its type constructor is followed by an additional description:
@@ -105,7 +107,7 @@ The description of a function signature. Its type constructor is followed by an
 | return_count | `varuint1` | the number of results from the function |
 | return_type | `value_type?` | the result type of the function (if return_count is 1) |
 
-Note: In the future, `return_count` and `return_type` might be generalised to allow multiple values.
+Note: In the [future :unicorn:][future multiple return], `return_count` and `return_type` might be generalised to allow multiple values.
 
 ## Other Types
 
@@ -150,7 +152,7 @@ A packed tuple that describes the limits of a
 | initial | `varuint32` | initial length (in units of table elements or wasm pages) |
 | maximum | `varuint32`? | only present if specified by `flags` |
 
-Note: In the future, the "flags" field may be extended, e.g., to include a flag for sharing between threads.
+Note: In the [future :unicorn:][future threads], the "flags" field may be extended, e.g., to include a flag for sharing between threads.
 
 ### `init_expr`
 The encoding of an [initializer expression](Modules.md#initializer-expression)
@@ -221,7 +223,8 @@ The type section declares all function signatures that will be used in the modul
 | count | `varuint32` | count of type entries to follow |
 | entries | `func_type*` | repeated type entries as described below |
 
-Note: In the future, this section may contain other forms of type entries as well, which can be distinguished by the `form` field of the type encoding.
+Note: In the [future :unicorn:][future types],
+this section may contain other forms of type entries as well, which can be distinguished by the `form` field of the type encoding.
 
 ### Import section
 
@@ -503,7 +506,8 @@ The `br_table` operator implements an indirect branch. It accepts an optional va
 branches to the block or loop at the given offset within the `target_table`. If the input value is 
 out of range, `br_table` branches to the default target.
 
-Note: Gaps in the opcode space, here and elsewhere, are reserved for future extensions.
+Note: Gaps in the opcode space, here and elsewhere, are reserved for
+[future :unicorn:][future general] extensions.
 
 ## Call operators ([described here](Semantics.md#calls))
 
@@ -512,7 +516,9 @@ Note: Gaps in the opcode space, here and elsewhere, are reserved for future exte
 | `call` | `0x10` | function_index : `varuint32` | call a function by its [index](Modules.md#function-index-space) |
 | `call_indirect` | `0x11` | type_index : `varuint32`, reserved : `varuint1` | call a function indirect with an expected signature |
 
-The `call_indirect` operator takes a list of function arguments and as the last operand the index into the table. Its `reserved` immediate is for future use and must be `0` in the MVP.
+The `call_indirect` operator takes a list of function arguments and as the last
+operand the index into the table. Its `reserved` immediate is for
+[future :unicorn:][future multiple tables] use and must be `0` in the MVP.
 
 ## Parametric operators ([described here](Semantics.md#type-parametric-operators))
 
@@ -571,10 +577,12 @@ The `memory_immediate` type is encoded as follows:
 As implied by the `log2(alignment)` encoding, the alignment must be a power of 2.
 As an additional validation criteria, the alignment must be less or equal to 
 natural alignment. The bits after the
-`log(memory-access-size)` least-significant bits must be set to 0. These bits are reserved for future use
+`log(memory-access-size)` least-significant bits must be set to 0. These bits
+are reserved for [future :unicorn:][future threads] use
 (e.g., for shared memory ordering requirements).
 
-The `reserved` immediate to the `current_memory` and `grow_memory` operators is for future use and must be 0 in the MVP.
+The `reserved` immediate to the `current_memory` and `grow_memory` operators is
+for [future :unicorn:][future multiple tables] use and must be 0 in the MVP.
 
 ## Constants ([described here](Semantics.md#constants))
 
@@ -727,3 +735,10 @@ The `reserved` immediate to the `current_memory` and `grow_memory` operators is
 | `i64.reinterpret/f64` | `0xbd` | | |
 | `f32.reinterpret/i32` | `0xbe` | | |
 | `f64.reinterpret/i64` | `0xbf` | | |
+
+[future general]: PostMVP.md
+[future multiple return]: PostMVP.md#multiple-return
+[future threads]: PostMVP.md#threads
+[future types]: FutureFeatures.md#more-table-operators-and-types
+[future multiple tables]: FutureFeatures.md#multiple-tables-and-memories
+[future compression]: https://github.com/WebAssembly/decompressor-prototype/blob/master/CompressionLayer1.md

CAndC++.md

@@ -20,7 +20,7 @@ has an LP64 data model, meaning that `long` and pointer types will be
 
 [The MVP](MVP.md) will support only wasm32; support for wasm64 will be
 added in the future to support
-[64-bit address spaces](FutureFeatures.md#linear-memory-bigger-than-4-gib).
+[64-bit address spaces :unicorn:][future 64-bit].
 
 `float` and `double` are the IEEE 754-2008 single- and double-precision types,
 which are native in WebAssembly. `long double` is the IEEE 754-2008
@@ -128,3 +128,6 @@ WebAssembly has very limited [nondeterminism](Nondeterminism.md), so it is
 expected that compiled WebAssembly programs will behave very consistently
 across different implementations, and across different versions of the same
 implementation.
+
+[future 64-bit]: FutureFeatures.md#linear-memory-bigger-than-4-gib
+

DynamicLinking.md

@@ -69,7 +69,7 @@ To implement run-time dynamic linking (e.g., `dlopen` and `dlsym`):
   search the instances's exports, append the found function to the function
   table (using host-defined functionality in the MVP, but directly from
   WebAssembly code in the
-  [future](FutureFeatures.md#more-table-operators-and-types)) and return the
+  [future :unicorn:][future types]) and return the
   table index of the appended element to the caller.
 
 Note that the representation of a C function-pointer in WebAssembly is an index
@@ -91,3 +91,5 @@ runtimes will be ABI agnostic, so it will be possible to use a non-standard ABI
 for specialized purposes.
 
   [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface
+
+[future types]: FutureFeatures.md#more-table-operators-and-types

FAQ.md

@@ -24,8 +24,8 @@ There are two main benefits WebAssembly provides:
 2. By avoiding the simultaneous asm.js constraints of [AOT][]-[compilability][]
    and good performance even on engines without
    [specific asm.js optimizations][], a new standard makes it *much easier* to
-   add the [features](FutureFeatures.md) required to reach native levels of
-   performance.
+   add the [features :unicorn:][future features] required to reach native
+   levels of performance.
 
   [experiments]: BinaryEncoding.md#why-a-binary-encoding-instead-of-a-text-only-representation
   [streaming]: https://www.w3.org/TR/streams-api/
@@ -93,9 +93,10 @@ However, by [integrating with JavaScript at the ES6 Module interface](Modules.md
 web developers don't need to write C++ to take advantage of libraries that others have written; 
 reusing a modular C++ library can be as simple as [using a module from JavaScript](http://jsmodules.io).
 
-Beyond the MVP, another [high-level goal](HighLevelGoals.md) 
-is to improve support for languages other than C/C++.  This includes [allowing WebAssembly code to 
-allocate and access garbage-collected (JavaScript, DOM, Web API) objects](FutureFeatures.md#gcdom-integration). 
+Beyond the MVP, another [high-level goal](HighLevelGoals.md)
+is to improve support for languages other than C/C++.  This includes [allowing WebAssembly code to
+allocate and access garbage-collected (JavaScript, DOM, Web API) objects
+:unicorn:][future dom].
 Even before GC support is added to WebAssembly, it is possible to compile a language's VM 
 to WebAssembly (assuming it's written in portable C/C++) and this has already been demonstrated 
 ([1](http://ruby.dj), [2](https://kripken.github.io/lua.vm.js/lua.vm.js.html),
@@ -177,7 +178,7 @@ together in a number of configurations:
   today) allowing developers to reuse popular WebAssembly libraries just like
   JavaScript libraries today.
 * When WebAssembly
-  [gains the ability to access garbage-collected objects](FutureFeatures.md#gcdom-integration),
+  [gains the ability to access garbage-collected objects :unicorn:][future dom],
   those objects will be shared with JavaScript, and not live in a walled-off
   world of their own.
 
@@ -283,7 +284,7 @@ it, but fast-math flags are not believed to be important enough:
    would be feature tests allowing WebAssembly code to determine which SIMD
    types to use on a given platform.
  * When WebAssembly
-   [adds an FMA operator](FutureFeatures.md#additional-floating-point-operators),
+   [adds an FMA operator :unicorn:][future floating point],
    folding multiply and add sequences into FMA operators will be possible.
  * WebAssembly doesn't include its own math functions like `sin`, `cos`, `exp`,
    `pow`, and so on. WebAssembly's strategy for such functions is to allow them
@@ -312,7 +313,7 @@ operators:
 * the MVP starts with the ability to grow linear memory via a
   [`grow_memory`](Semantics.md#resizing) operator;
 * proposed
-  [future features](FutureFeatures.md#finer-grained-control-over-memory) would
+  [future features :unicorn:][future memory control] would
   allow the application to change the protection and mappings for pages in the
   contiguous range `0` to `memory_size`.
 
@@ -388,3 +389,8 @@ accessible through regular JavaScript. However, if a wasm VM is provided as an
 [“app execution platform”](NonWeb.md) by a specific vendor, it might provide 
 access to [proprietary platform-specific APIs](Portability.md#api) of e.g. 
 Android / iOS. 
+
+[future features]: FutureFeatures.md
+[future dom]: FutureFeatures.md#gcdom-integration
+[future floating point]: FutureFeatures.md#additional-floating-point-operators
+[future memory control]: FutureFeatures.md#finer-grained-control-over-memory

FeatureTest.md

@@ -2,8 +2,9 @@ See [rationale](Rationale.md#feature-testing---motivating-scenarios) for motivat
 
 # Feature Test
 
-[PostMVP](PostMVP.md), applications will be able to query which features are
-supported via [`has_feature` or a similar API](PostMVP.md#feature-testing). This
+[PostMVP :unicorn:][future general], applications will be able to query which features are
+supported via
+[`has_feature` or a similar API :unicorn:][future feature testing]. This
 accounts for the pragmatic reality that features are shipped in different orders
 at different times by different engines.
 
@@ -40,15 +41,15 @@ it can be constant-folded by WebAssembly engines.
 
 To illustrate, consider 4 examples:
 
-* [`i32.min_s`](FutureFeatures.md#additional-integer-operators) - Strategy 2
+* [`i32.min_s` :unicorn:][future integer] - Strategy 2
   could be used to translate `(i32.min_s lhs rhs)` into an equivalent expression
   that stores `lhs` and `rhs` in locals then uses `i32.lt_s` and `select`.
-* [Threads](PostMVP.md#threads) - If an application uses `#ifdef` extensively
+* [Threads :unicorn:][future threads] - If an application uses `#ifdef` extensively
   to produce thread-enabled/disabled builds, Strategy 1 would be appropriate.
   However, if the application was able to abstract use of threading to a few
   primitives, Strategy 2 could be used to patch in the right primitive 
   implementation.
-* [`mprotect`](FutureFeatures.md#finer-grained-control-over-memory) - If engines
+* [`mprotect` :unicorn:][future memory control] - If engines
   aren't able to use OS signal handling to implement `mprotect` efficiently,
   `mprotect` may become a permanently optional feature. For uses of `mprotect`
   that are not necessary for correctness (but rather just catching bugs),
@@ -96,5 +97,11 @@ polyfill would then replace `foo` with `foo_f64x2` if
 coarser granularity substitution. Since this is all in userspace, the strategy
 can evolve over time.
 
-See also the [better feature testing support](FutureFeatures.md#better-feature-testing-support)
+See also the [better feature testing support :unicorn:][future feature testing]
 future feature.
+
+[future general]: PostMVP.md
+[future feature testing]: PostMVP.md#feature-testing
+[future integer]: FutureFeatures.md#additional-integer-operators
+[future thread]: PostMVP.md#threads
+[future memory control]: FutureFeatures.md#finer-grained-control-over-memory

FutureFeatures.md

@@ -2,7 +2,8 @@
 
 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](PostMVP.md)
+of the [Minimum Viable Product](MVP.md) or the essential
+[post-MVP :unicorn:](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).
@@ -420,6 +421,11 @@ of WebAssembly in browsers:
   custom compression (on top of the spec-defined binary format, under generic
   HTTP `Content-Encoding` compression).
 
+## Multiple Return
+
+The stack based nature of WebAssembly lends itself to the possibility
+of supporting multiple return values from blocks / functions.
+
 ## Multiple Tables and Memories
 
 The MVP limits modules to at most one memory and at most one table (the default

GC.md

@@ -1,4 +1,6 @@
-# GC / DOM / Web API Integration
+# GC / DOM / Web API Integration [:unicorn:][future general]
+
+## NOTE: This is a [future :unicorn:][future general] feature! ##
 
 After the [MVP](MVP.md), to realize the [high-level goals](HighLevelGoals.md)
 of (1) integrating well with the existing Web platform and (2) supporting
@@ -164,3 +166,4 @@ consider for this feature, but a few points of tentative agreement are:
   [Typed Objects](https://github.com/nikomatsakis/typed-objects-explainer/)
   proposal.
 
+[future general]: PostMVP.md

HighLevelGoals.md

@@ -12,7 +12,7 @@
       aimed at [C/C++](CAndC++.md);
     * a [follow-up to the MVP](PostMVP.md) which adds several more
       essential features; and
-    * [additional features](FutureFeatures.md), specified iteratively and
+    * [additional features :unicorn:][future features], specified iteratively and
       prioritized by feedback and experience, including support for languages
       other than C/C++.
 3. Design to execute within and integrate well with the *existing*
@@ -33,3 +33,5 @@
       clang port ([why LLVM first?](FAQ.md#which-compilers-can-i-use-to-build-webassembly-programs));
     * promote other compilers and tools targeting WebAssembly; and
     * enable other useful [tooling](Tooling.md).
+
+[future features]: FutureFeatures.md

JS.md

@@ -1,18 +1,12 @@
 # JavaScript API
 
 In the [MVP](MVP.md), the only way to access WebAssembly on the Web is through
-an explicit JS API which is defined below. (In the future, WebAssembly may also
+an explicit JS API which is defined below.
+(In the [future :unicorn:][future general], WebAssembly may also
 be loaded and run directly from an HTML `<script type='module'>` tag—and
 any other Web API that loads ES6 modules via URL—as part of 
 [ES6 Module integration](Modules.md#integration-with-es6-modules).)
 
-*Note: current experimental WebAssembly implementations expose a single
-all-in-one function `Wasm.instantiateModule(bytes, imports)` which is used
-by the current [demo](http://webassembly.github.io/demo). This function is
-basically equivalent to 
-`new WebAssembly.Instance(new WebAssembly.Module(bytes), imports)`
-as defined below and will be removed at some point in the future.*
-
 ## Traps
 
 Whenever WebAssembly semantics specify a [trap](Semantics.md#traps),
@@ -90,7 +84,7 @@ The asynchronous compilation is logically performed on a copy of the state of
 the given `BufferSource` captured during the call to `compile`; subsequent mutations
 of the `BufferSource` after `compile` return do not affect ongoing compilations.
 
-In the [future](FutureFeatures.md#streaming-compilation), this function can be
+In the [future :unicorn:][future streaming], this function can be
 extended to accept a [stream](https://streams.spec.whatwg.org), thereby enabling
 asynchronous, background, streaming compilation.
 
@@ -481,8 +475,7 @@ Let `element` be the result of calling [`Get`](http://tc39.github.io/ecma262/#se
 If `element` is not the string `"anyfunc"`, a [`TypeError`](https://tc39.github.io/ecma262/#sec-native-error-types-used-in-this-standard-typeerror)
 is thrown.
 (Note: this check is intended to be relaxed in the
-[future](FutureFeatures.md#more-table-operators-and-types) to allow different
-element types.)
+[future :unicorn:][future types] to allow different element types.)
 
 Let `initial` be [`ToNonWrappingUint32`](#tononwrappinguint32)([`Get`](http://tc39.github.io/ecma262/#sec-get-o-p)(`tableDescriptor`, `"initial"`)).
 
@@ -638,3 +631,7 @@ fetch('demo.wasm').then(response =>
 
 * `WebAssembly.Module` `exports`/`imports` properties (reflection)
 * JS API for cyclic imports (perhaps a Promise-returning `WebAssembly.instantiate`?)
+
+[future general]: PostMVP.md
+[future streaming]: FutureFeatures.md#streaming-compilation
+[future types]: FutureFeatures.md#more-table-operators-and-types