Extensible encoding of function signatures (#640)

* Prettify section names

* Restructure encoding of function signatures

* Revert "[Binary 11] Update the version number to 0xB."

* Leave index space for growing the number of base types

* Comments addressed

* clarify how export/import names convert to JS strings (#569) (#573)

* When embedded in the web, clarify how export/import names convert to JS strings (#569)

* Fixes suggested by @jf

* Address more feedback

Added a link to http://monsur.hossa.in/2012/07/20/utf-8-in-javascript.html.  Simplified the decoding algorithm thanks to Luke's feedback.

* Access to proprietary APIs apart from HTML5 (#656)

* comments

Author: rossberg

BinaryEncoding.md

@@ -35,6 +35,9 @@ A four-byte little endian unsigned integer.
 ### varint32
 A [Signed LEB128](https://en.wikipedia.org/wiki/LEB128#Signed_LEB128) variable-length integer, limited to int32 values.
 
+### varuint1
+A [LEB128](https://en.wikipedia.org/wiki/LEB128) variable-length integer, limited to the values 0 or 1. `varuint1` values may contain leading zeros. (This type is mainly used for compatibility with potential future extensions.)
+
 ### varuint32
 A [LEB128](https://en.wikipedia.org/wiki/LEB128) variable-length integer, limited to uint32 values. `varuint32` values may contain leading zeros.
 
@@ -75,8 +78,8 @@ The module starts with a preamble of two fields:
 
 | Field | Type | Description |
 | ----- |  ----- | ----- |
-| magic number | `uint32` |  Magic number `0x6d736100` == `'\0asm'`. |
-| version | `uint32` | Version number `11` == `0x0b`. The version for MVP will be reset to `1`. |
+| magic number | `uint32` |  Magic number `0x6d736100` (i.e., '\0asm') |
+| version | `uint32` | Version number, currently 10. The version for MVP will be reset to 1. |
 
 This preamble is followed by a sequence of sections. Each section is identified by an
 immediate string. Sections whose identity is unknown to the WebAssembly
@@ -117,15 +120,19 @@ The type section declares all function signatures that will be used in the modul
 
 | Field | Type | Description |
 | ----- |  ----- | ----- |
-| count | `varuint32` | count of signature entries to follow |
+| count | `varuint32` | count of type entries to follow |
 | entries | `type_entry*` | repeated type entries as described below |
 
 #### Type entry
 | Field | Type | Description |
 | ----- |  ----- | ----- |
+| form | `uint8` | `0x40`, indicating a function type |
 | param_count | `varuint32` | the number of parameters to the function |
-| return_type | `value_type?` | the return type of the function, with `0` indicating no return type |
 | param_types | `value_type*` | the parameter types of the function |
+| 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, this section may contain other forms of type entries as well, which can be distinguished by the `form` field.)
 
 ### Import section
 
@@ -216,7 +223,7 @@ The start section declares the [start function](Modules.md#module-start-function
 
 ID: `code`
 
-The code section assigns a body to every function in the module.
+The code section contains a body for every function in the module.
 The count of function declared in the [function section](#function-section)
 and function bodies defined in this section must be the same and the `i`th
 declaration corresponds to the `i`th function body.
@@ -230,7 +237,7 @@ declaration corresponds to the `i`th function body.
 
 ID: `data`
 
-The data section declares the initialized data that should be loaded
+The data section declares the initialized data that is loaded
 into the linear memory.
 
 | Field | Type | Description |

FAQ.md

@@ -389,3 +389,12 @@ those that motivated the development of the
 
 Even Knuth found it worthwhile to give us his opinion on this issue at point,
 [a flame about 64-bit pointers](http://www-cs-faculty.stanford.edu/~uno/news08.html).
+
+## Will I be able to access proprietary platform APIs (e.g. Android / iOS)?
+
+Yes but it will depend on the _WebAssembly embedder_. Inside a browser you'll 
+get access to the same HTML5 and other browser-specific APIs which are also 
+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. 

Web.md

@@ -28,6 +28,35 @@ WebAssembly's [modules](Modules.md) allow for natural [integration with
 the ES6 module system](Modules.md#integration-with-es6-modules) and allow
 synchronous calling to and from JavaScript.
 
+### Function Names
+
+A WebAssembly module imports and exports functions. WebAssembly names functions
+using arbitrary-length byte sequences. Any 8-bit values are permitted in a
+WebAssembly name, including the null byte and byte sequences that don't
+correspond to any Unicode code point regardless of encoding. The most natural
+Web representation of a mapping of function names to functions is a JS object
+in which each function is a property. Property names in JS are UTF-16 encoded
+strings. A WebAssembly module may fail validation on the Web if it imports or
+exports functions whose names do not transcode cleanly to UTF-16 according to
+the following conversion algorithm, assuming that the WebAssembly name is in a
+`Uint8Array` called `array`:
+
+```
+function convertToJSString(array)
+{
+  var string = "";
+  for (var i = 0; i < array.length; ++i)
+    string += String.fromCharCode(array[i]);
+  return decodeURIComponent(escape(string));
+}
+```
+
+This performs the UTF8 decoding (`decodeURIComponent(unescape(string))`) using
+a [common JS idiom](http://monsur.hossa.in/2012/07/20/utf-8-in-javascript.html).
+Transcoding failure is detected by `decodeURIComponent`, which may throw
+`URIError`. If it does, the WebAssembly module will not validate. This validation
+rule is only mandatory for Web embedding.
+
 ## Aliasing linear memory from JS
 
 If [allowed by the module](Modules.md#linear-memory-section), JavaScript can