From f78543d9e576ffa7a8ef4a3395ca08e8c9f8fae4 Mon Sep 17 00:00:00 2001 From: rossberg-chromium Date: Tue, 5 Apr 2016 14:07:21 +0200 Subject: [PATCH 1/8] Prettify section names --- BinaryEncoding.md | 77 ++++++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 3030270d..396aae56 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -92,42 +92,42 @@ for all sections. The encoding of all sections begins as follows: Each section is optional and may appear at most once. Known sections (from this list) may not appear out of order. -* [Signatures](#signatures-section) section -* [Import Table](#import-table-section) section -* [Function Signatures](#function-signatures-section) section -* [Indirect Function Table](#indirect-function-table-section) section +* [Type](#type-section) section +* [Import](#import-section) section +* [Function](#function-section) section +* [Indirection](#indirection-section) section * [Memory](#memory-section) section -* [Export Table](#export-table-section) section -* [Start Function](#start-function-section) section -* [Function Bodies](#function-bodies-section) section -* [Data Segments](#data-segments-section) section +* [Export](#export-section) section +* [Start](#start-section) section +* [Code](#code-section) section +* [Data](#data-section) section * [Names](#names-section) section The end of the last present section must coincide with the last byte of the module. The shortest valid module is 8 bytes (`magic number`, `version`, followed by zero sections). -### Signatures section +### Type section -ID: `signatures` +ID: `types` -The signatures section declares all function signatures that will be used in the module. +The type section declares all function signatures that will be used in the module. | Field | Type | Description | | ----- | ----- | ----- | | count | `varuint32` | count of signature entries to follow | -| entries | `signature_entry*` | repeated signature entries as described below | +| entries | `type_entry*` | repeated type entries as described below | -#### Signature entry +#### Type entry | Field | Type | Description | | ----- | ----- | ----- | | 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 | -### Import Table section +### Import section -ID: `import_table` +ID: `imports` The import section declares all imports that will be used in the module. @@ -145,29 +145,29 @@ The import section declares all imports that will be used in the module. | function_len | `varuint32` | function string length | | function_str | `bytes` | function string of `function_len` bytes | -### Function Signatures section +### Function section -ID: `function_signatures` +ID: `functions` -The Function Signatures section declares the signatures of all functions in the -module. +The function section _declares_ the signatures of all functions in the +module (their definitions appear in the [code section](#code-section)). | Field | Type | Description | | ----- | ----- | ----- | | count | `varuint32` | count of signature indices to follow | -| signatures | `varuint32*` | sequence of indices into the Signature section | +| types | `varuint32*` | sequence of indices into the type section | -### Indirect Function Table section +### Indirection section -ID: `function_table` +ID: `indirect` -The indirect function table section defines the module's +The indirection section defines the module's [indirect function table](AstSemantics.md#calls). | Field | Type | Description | | ----- | ----- | ----- | | count | `varuint32` | count of entries to follow | -| entries | `varuint32*` | repeated indexes into the function table | +| entries | `varuint32*` | repeated indexes into the function section | ### Memory section @@ -182,11 +182,11 @@ associated with the module. | max_mem_pages | `varuint32` | maximum memory size in 64KiB pages | | exported | `uint8` | `1` if the memory is visible outside the module | -### Export Table section +### Export section -ID: `export_table` +ID: `exports` -The export table section declares all exports from the module. +The export section declares all exports from the module. | Field | Type | Description | | ----- | ----- | ----- | @@ -200,34 +200,35 @@ The export table section declares all exports from the module. | function_len | `varuint32` | function string length | | function_str | `bytes` | function string of `function_len` bytes | -### Start Function section +### Start section -ID: `start_function` +ID: `start` -The start function section declares the [start function](Modules.md#module-start-function). +The start section declares the [start function](Modules.md#module-start-function). | Field | Type | Description | | ----- | ----- | ----- | | index | `varuint32` | start function index | -### Function Bodies section +### Code section -ID: `function_bodies` +ID: `code` -The Function Bodies section assigns a body to every function in the module. -The count of function signatures and function bodies must be the same and the `i`th -signature corresponds to the `i`th function body. +The code section assigns a body to 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. | Field | Type | Description | | ----- | ----- | ----- | ----- | | count | `varuint32` | count of function bodies to follow | | bodies | `function_body*` | sequence of [Function Bodies](#function-bodies) | -### Data Segments section +### Data section -ID: `data_segments` +ID: `data` -The data segments section declares the initialized data that should be loaded +The data section declares the initialized data that should be loaded into the linear memory. | Field | Type | Description | From bb8a6e43af9bc6b5b904a5124062b59ae06d1304 Mon Sep 17 00:00:00 2001 From: rossberg-chromium Date: Tue, 5 Apr 2016 14:14:49 +0200 Subject: [PATCH 2/8] Restructure encoding of function signatures --- BinaryEncoding.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 396aae56..51588a42 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -119,11 +119,15 @@ The type section declares all function signatures that will be used in the modul | entries | `type_entry*` | repeated type entries as described below | #### Type entry -| Field | Type | Description | +| Field | Type/Value | Description | | ----- | ----- | ----- | +| constructor | `0x05` | the function type constructor | | 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 | `uint8` | the number of results from the function (0 or 1) | +| 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.) ### Import section From 7c8be53bad55836ac5f0c6d1de70006552162901 Mon Sep 17 00:00:00 2001 From: titzer Date: Tue, 5 Apr 2016 16:51:22 +0200 Subject: [PATCH 3/8] Revert "[Binary 11] Update the version number to 0xB." --- BinaryEncoding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 86a817b9..3030270d 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -75,8 +75,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 From c63829e151ae24393e78887b630f108b75d387ad Mon Sep 17 00:00:00 2001 From: rossberg-chromium Date: Tue, 5 Apr 2016 17:22:34 +0200 Subject: [PATCH 4/8] Leave index space for growing the number of base types --- BinaryEncoding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 51588a42..3684f4a0 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -121,7 +121,7 @@ The type section declares all function signatures that will be used in the modul #### Type entry | Field | Type/Value | Description | | ----- | ----- | ----- | -| constructor | `0x05` | the function type constructor | +| constructor | `0x40` | the function type constructor | | param_count | `varuint32` | the number of parameters to the function | | param_types | `value_type*` | the parameter types of the function | | return_count | `uint8` | the number of results from the function (0 or 1) | From ec21463b44f46263fb81bdcb1f3cdf56a58bf93f Mon Sep 17 00:00:00 2001 From: rossberg-chromium Date: Wed, 6 Apr 2016 14:01:08 +0200 Subject: [PATCH 5/8] Comments addressed --- BinaryEncoding.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 3684f4a0..7ab35b8b 100644 --- a/BinaryEncoding.md +++ b/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. @@ -115,19 +118,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/Value | Description | +| Field | Type | Description | | ----- | ----- | ----- | -| constructor | `0x40` | the function type constructor | +| form | `uint8` | `0x40`, indicating a function type | | param_count | `varuint32` | the number of parameters to the function | | param_types | `value_type*` | the parameter types of the function | -| return_count | `uint8` | the number of results from the function (0 or 1) | +| 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.) +(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 From 04c63fb2b26f25b2bfd88569baf8711f146e4d06 Mon Sep 17 00:00:00 2001 From: pizlonator Date: Fri, 15 Apr 2016 13:17:37 -0700 Subject: [PATCH 6/8] 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. --- Web.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Web.md b/Web.md index 3582c444..d9345d7d 100644 --- a/Web.md +++ b/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 From 2312afd61751bd995341fd477381a40defb79742 Mon Sep 17 00:00:00 2001 From: Alexander Orlov Date: Fri, 15 Apr 2016 22:18:57 +0200 Subject: [PATCH 7/8] Access to proprietary APIs apart from HTML5 (#656) --- FAQ.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/FAQ.md b/FAQ.md index d61f5f1e..901b2744 100644 --- a/FAQ.md +++ b/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. From aa0407d5862acf3269216c4c4e9ab5bb9c5e60b4 Mon Sep 17 00:00:00 2001 From: rossberg-chromium Date: Tue, 19 Apr 2016 15:03:33 +0200 Subject: [PATCH 8/8] comments --- BinaryEncoding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/BinaryEncoding.md b/BinaryEncoding.md index c7f45ade..efb1df2e 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -223,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. @@ -237,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 |