From 01704645e0f96dee6cdb86c15b1d2896c1125a6e Mon Sep 17 00:00:00 2001 From: Douglas Crosher Date: Mon, 22 Feb 2016 10:03:26 +1100 Subject: Encode the memory sizes in units of pages, and use a leb128 encoding. --- BinaryEncoding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index bfdbe30..fd5c031 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -83,8 +83,8 @@ A module may contain at most one memory section. | Field | Type | Description | | ----- | ----- | ----- | | id = `0x00` | `uint8` | section identifier for memory | -| min_mem_size | `uint8` | minimize memory size as a power of `2` | -| max_mem_size | `uint8` | maximum memory size as a power of `2` | +| min_mem_pages | `varuint32` | minimize memory size in 64KiB pages | +| max_mem_pages | `varuint32` | maximum memory size in 64KiB pages | | exported | `uint8` | `1` if the memory is visible outside the module | ### Signatures section -- cgit v1.2.3 From 27cfc727482d52ce8c133a95ac655418ad164812 Mon Sep 17 00:00:00 2001 From: titzer Date: Tue, 23 Feb 2016 08:16:41 -0800 Subject: Add import table. --- BinaryEncoding.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index bfdbe30..8f6e610 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -104,6 +104,24 @@ A module may contain at most one signatures section. | 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 +The import section declares all imports that will be used in the module. +A module may contain at most one import table section. + +| Field | Type | Description | +| ----- | ----- | ----- | +| id = `0x08` | `uint8` | section identifier for imports | +| count | `varuint32` | count of import entries to follow | +| entries | `import_entry*` | repeated import entries as described below | + +#### Import entry +| Field | Type | Description | +| ----- | ----- | ----- | +| sig_index | `uint16` | signature index of the import | +| module_name | `uint32` | offset of the string representing the module name | +| func_name | `uint32` | offset of the string representing the function name | + + ### Functions section The Functions section declares the functions in the module and must be preceded by a [Signatures](#signatures-section) section. A module may contain at most one functions section. -- cgit v1.2.3 From a7d67f1f03d5000c1a036499d932327060349e24 Mon Sep 17 00:00:00 2001 From: JF Bastien Date: Thu, 25 Feb 2016 09:04:28 -0800 Subject: Unknown sections Fixes #208. A later PR will make sure all sections start with the same format (so all sections use bytes, instead of count, making it easy to know the byte count of unknown sections). We'll also use strings instead. --- BinaryEncoding.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index fd5c031..a416c7a 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -187,13 +187,15 @@ stored to from dedicated instructions. | type | `uint8` | the type of the global, as a memory type | | exported | `uint8` | a boolean indicating whether the global variable is exported | -### WorkInProgress: WLL section +### Unknown sections | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x11` | `uint8` | section identifier for globals | -| size | `varuint32` | size of this section in bytes | -| body | `bytes` | contents of this section | +| id | `uint8` | section identifier | +| size | `varuint32` | size of this section in bytes | +| body | `bytes` | contents of this section | + +Sections whose ID is unknown to the WebAssembly implementation are ignored. # AST Encoding -- cgit v1.2.3 From f42df8dc1ed183c9178577b451e18ebc37cc314d Mon Sep 17 00:00:00 2001 From: titzer Date: Thu, 25 Feb 2016 09:43:53 -0800 Subject: Update text: "offset from start of the module" --- BinaryEncoding.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 8f6e610..90f7830 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -118,8 +118,8 @@ A module may contain at most one import table section. | Field | Type | Description | | ----- | ----- | ----- | | sig_index | `uint16` | signature index of the import | -| module_name | `uint32` | offset of the string representing the module name | -| func_name | `uint32` | offset of the string representing the function name | +| module_name | `uint32` | offset from the start of the module of the string representing the module name | +| func_name | `uint32` | offset from the start of the module of the string representing the function name | ### Functions section -- cgit v1.2.3 From 7c06cda04a9e55e2434be656fce5468e6011c807 Mon Sep 17 00:00:00 2001 From: Douglas Crosher Date: Fri, 26 Feb 2016 12:42:50 +1100 Subject: Name the sections by strings, and add a size for all sections. --- BinaryEncoding.md | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 671e94d..5665aa1 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -73,27 +73,36 @@ Strings referenced by the module (i.e. function names) are encoded as null-termi The following documents the current prototype format. This format is based on and supersedes the v8-native prototype format, originally in a [public design doc](https://docs.google.com/document/d/1-G11CnMA0My20KI9D7dBR6ZCPOBCRD0oCH6SHCPFGx0/edit?usp=sharing). ## High-level structure -A module contains a sequence of sections, each identified by a *section identifier byte* whose encodings -are listed below. +A module contains a sequence of sections. Sections can in general be repeated, but some can occur only once or have dependant sections that must preceed them but not immediately as unknown sections can occur in any order. Each section is identified by an immediate string. Sections whose identity is unknown to the WebAssembly implementation are ignored and this is supported by including the size in bytes for all sections. The encoding of all sections begins as follows: + +| Field | Type | Description | +| ----- | ----- | ----- | +| size | `varuint32` | size of this section in bytes, excluding this size | +| id_len | `varuint32` | section identifier string length | +| id_str | `bytes` | section identifier string of id_len bytes | ### Memory section + +ID: `memory` + The memory section declares the size and characteristics of the memory associated with the module. A module may contain at most one memory section. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x00` | `uint8` | section identifier for memory | | min_mem_pages | `varuint32` | minimize memory size in 64KiB pages | | max_mem_pages | `varuint32` | maximum memory size in 64KiB pages | | exported | `uint8` | `1` if the memory is visible outside the module | ### Signatures section + +ID: `signatures` + The signatures section declares all function signatures that will be used in the module. A module may contain at most one signatures section. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x01` | `uint8` | section identifier for signatures | | count | `varuint32` | count of signature entries to follow | | entries | `signature_entry*` | repeated signature entries as described below | @@ -105,12 +114,14 @@ A module may contain at most one signatures section. | param_types | `value_type*` | the parameter types of the function | ### Import table section + +ID: `import_table` + The import section declares all imports that will be used in the module. A module may contain at most one import table section. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x08` | `uint8` | section identifier for imports | | count | `varuint32` | count of import entries to follow | | entries | `import_entry*` | repeated import entries as described below | @@ -123,11 +134,13 @@ A module may contain at most one import table section. ### Functions section + +ID: `functions` + The Functions section declares the functions in the module and must be preceded by a [Signatures](#signatures-section) section. A module may contain at most one functions section. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x02` | `uint8` | section identifier for functions | | count | `varuint32` | count of function entries to follow | | entries | `function_entry*` | repeated function entries as described below | @@ -149,12 +162,14 @@ must contain a function body. Imported and exported functions must have a name. | body | `bytes` | `flags[0] == 0` | function body | ### Data Segments section + +ID: `data_segments` + The data segemnts section declares the initialized data that should be loaded into the linear memory. A module may only contain one data segments section. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x04` | `uint8` | section identifier for data segments | | count | `varuint32` | count of data segments to follow | | entries | `data_segment*` | repeated data segments as described below | @@ -166,31 +181,37 @@ A module may only contain one data segments section. - ```uint8```: ```1``` if the segment's data should be automatically loaded into memory at module load time. ### Indirect Function Table section + +ID: `function_table` + The indirect function table section declares the size and entries of the indirect function table, which consist of indexes into the [Functions](#functions-section) section. This section must be preceded by a [Functions](#functions-section) section. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x05` | `uint8` | section identifier for indirect function table | | count | `varuint32` | count of entries to follow | | entries | `uint16*` | repeated indexes into the function table | ### End section + +ID: `end` + This indicates the end of the sections. Additional data that follows this section marker is not interpreted by the decoder. It can used, for example, to store function names or data segment bodies. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x06` | `uint8` | section identifier for end of sections | ### Nonstandard: Globals section + +ID: `globals` + A module may only contain one globals section. This section is currently for V8 internal use. | Field | Type | Description | | ----- | ----- | ----- | -| id = `0x03` | `uint8` | section identifier for globals | | count | `varuint32` | count of global variable entries to follow | | entries | `global_variable*` | repeated global variable entries as described below | @@ -209,8 +230,6 @@ stored to from dedicated instructions. | Field | Type | Description | | ----- | ----- | ----- | -| id | `uint8` | section identifier | -| size | `varuint32` | size of this section in bytes | | body | `bytes` | contents of this section | Sections whose ID is unknown to the WebAssembly implementation are ignored. -- cgit v1.2.3 From e6102f6e5dfbaffae8692e974e4e588fd9adfdef Mon Sep 17 00:00:00 2001 From: Douglas Crosher Date: Sat, 27 Feb 2016 13:26:31 +1100 Subject: Document the Start Function section. --- BinaryEncoding.md | 47 +++++++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 18 deletions(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 5665aa1..811e264 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -89,7 +89,7 @@ The memory section declares the size and characteristics of the memory associate A module may contain at most one memory section. | Field | Type | Description | -| ----- | ----- | ----- | +| ----- | ----- | ----- | | min_mem_pages | `varuint32` | minimize memory size in 64KiB pages | | max_mem_pages | `varuint32` | maximum memory size in 64KiB pages | | exported | `uint8` | `1` if the memory is visible outside the module | @@ -102,13 +102,13 @@ The signatures section declares all function signatures that will be used in the A module may contain at most one signatures section. | Field | Type | Description | -| ----- | ----- | ----- | -| count | `varuint32` | count of signature entries to follow | +| ----- | ----- | ----- | +| count | `varuint32` | count of signature entries to follow | | entries | `signature_entry*` | repeated signature entries as described below | #### Signature entry | Field | Type | Description | -| ----- | ----- | ----- | +| ----- | ----- | ----- | | param_count | `uint8` | 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 | @@ -121,13 +121,13 @@ The import section declares all imports that will be used in the module. A module may contain at most one import table section. | Field | Type | Description | -| ----- | ----- | ----- | -| count | `varuint32` | count of import entries to follow | +| ----- | ----- | ----- | +| count | `varuint32` | count of import entries to follow | | entries | `import_entry*` | repeated import entries as described below | #### Import entry | Field | Type | Description | -| ----- | ----- | ----- | +| ----- | ----- | ----- | | sig_index | `uint16` | signature index of the import | | module_name | `uint32` | offset from the start of the module of the string representing the module name | | func_name | `uint32` | offset from the start of the module of the string representing the function name | @@ -140,8 +140,8 @@ ID: `functions` The Functions section declares the functions in the module and must be preceded by a [Signatures](#signatures-section) section. A module may contain at most one functions section. | Field | Type | Description | -| ----- | ----- | ----- | -| count | `varuint32` | count of function entries to follow | +| ----- | ----- | ----- | +| count | `varuint32` | count of function entries to follow | | entries | `function_entry*` | repeated function entries as described below | #### Function Entry @@ -150,7 +150,7 @@ Each function entry describes a function that can be optionally named, imported must contain a function body. Imported and exported functions must have a name. Imported functions do not contain a body. | Field | Type | Present? | Description | -| ----- | ----- | ----- | ----- | +| ----- | ----- | ----- | ----- | | flags | `uint8` | always | flags indicating attributes of a function
bit `0` : a name is present
bit `1` : the function is an import
bit `2` : the function has local variables
bit `3` : the function is an export | | signature | `uint16` | always | index into the Signature section | | name | `uint32` | `flags[0] == 1` | name of the function as an offset within the module | @@ -161,6 +161,17 @@ must contain a function body. Imported and exported functions must have a name. | body size | `uint16` | `flags[0] == 0` | size of function body to follow, in bytes | | body | `bytes` | `flags[0] == 0` | function body | +### Start Function section + +ID: `start_function` + +A module may contain at most one start fuction section. +This section must be preceded by a [Functions](#functions-section) section. + +| Field | Type | Description | +| ----- | ----- | ----- | +| index | `varuint32` | start function index | + ### Data Segments section ID: `data_segments` @@ -169,8 +180,8 @@ The data segemnts section declares the initialized data that should be loaded in A module may only contain one data segments section. | Field | Type | Description | -| ----- | ----- | ----- | -| count | `varuint32` | count of data segments to follow | +| ----- | ----- | ----- | +| count | `varuint32` | count of data segments to follow | | entries | `data_segment*` | repeated data segments as described below | * ```varuint32```: The number of data segments in the section. @@ -189,8 +200,8 @@ of indexes into the [Functions](#functions-section) section. This section must be preceded by a [Functions](#functions-section) section. | Field | Type | Description | -| ----- | ----- | ----- | -| count | `varuint32` | count of entries to follow | +| ----- | ----- | ----- | +| count | `varuint32` | count of entries to follow | | entries | `uint16*` | repeated indexes into the function table | ### End section @@ -201,7 +212,7 @@ This indicates the end of the sections. Additional data that follows this sectio by the decoder. It can used, for example, to store function names or data segment bodies. | Field | Type | Description | -| ----- | ----- | ----- | +| ----- | ----- | ----- | ### Nonstandard: Globals section @@ -212,7 +223,7 @@ A module may only contain one globals section. This section is currently for V8 | Field | Type | Description | | ----- | ----- | ----- | -| count | `varuint32` | count of global variable entries to follow | +| count | `varuint32` | count of global variable entries to follow | | entries | `global_variable*` | repeated global variable entries as described below | #### Global Variable entry @@ -221,8 +232,8 @@ A global variable entry describes a variable outside the WASM linear memory. A G stored to from dedicated instructions. | Field | Type | Description | -| ----- | ----- | ----- | -| name | `uint32` | name of the global variable as an offset to a string in the module | +| ----- | ----- | ----- | +| name | `uint32` | name of the global variable as an offset to a string in the module | | type | `uint8` | the type of the global, as a memory type | | exported | `uint8` | a boolean indicating whether the global variable is exported | -- cgit v1.2.3 From d6898abafa98ff889454cfb11725d9ec3c9536b5 Mon Sep 17 00:00:00 2001 From: Michael Bebenita Date: Sat, 27 Feb 2016 10:01:37 -0800 Subject: Clarify encoding of varuint32 values. --- BinaryEncoding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 811e264..b0987fb 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -39,7 +39,7 @@ A two-byte little endian unsigned integer. A four-byte little endian unsigned integer. ### varuint32 -A [LEB128](https://en.wikipedia.org/wiki/LEB128) variable-length integer, limited to uint32 values. +A [LEB128](https://en.wikipedia.org/wiki/LEB128) variable-length integer, limited to uint32 values. `varuint32` values may contain leading zeros. ### value_type A single-byte unsigned integer indicating a [value type](AstSemantics.md#types). These types are encoded as: -- cgit v1.2.3 From 531a3cde90728ae59e247c1a0dca7025d9caa01b Mon Sep 17 00:00:00 2001 From: Douglas Crosher Date: Sat, 27 Feb 2016 14:03:19 +1100 Subject: Document the export table section. As implemented in https://codereview.chromium.org/1744713003/ --- BinaryEncoding.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index b0987fb..b6e3a6b 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -161,6 +161,26 @@ must contain a function body. Imported and exported functions must have a name. | body size | `uint16` | `flags[0] == 0` | size of function body to follow, in bytes | | body | `bytes` | `flags[0] == 0` | function body | +### Export Table section + +ID: `export_table` + +The export table section declares all exports from the module. +A module may contain at most one export table section. +This section must be preceded by a [Functions](#functions-section) section. + +| Field | Type | Description | +| ----- | ----- | ----- | +| count | `varuint32` | count of export entries to follow | +| entries | `export_entry*` | repeated export entries as described below | + +#### Export entry +| Field | Type | Description | +| ----- | ----- | ----- | +| sig_index | `uint16` | signature index of the export | +| func_index | `uint16` | index into the function table | +| func_name | `uint32` | offset from the start of the module of the string representing the export name | + ### Start Function section ID: `start_function` -- cgit v1.2.3 From 5c49b34d3562ec32228177fb71f17a85e583a60b Mon Sep 17 00:00:00 2001 From: Douglas Crosher Date: Sun, 28 Feb 2016 12:30:37 +1100 Subject: Document the magic number and version. As implemented in https://codereview.chromium.org/1740373002/ --- BinaryEncoding.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index b6e3a6b..33ca33d 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -73,7 +73,15 @@ Strings referenced by the module (i.e. function names) are encoded as null-termi The following documents the current prototype format. This format is based on and supersedes the v8-native prototype format, originally in a [public design doc](https://docs.google.com/document/d/1-G11CnMA0My20KI9D7dBR6ZCPOBCRD0oCH6SHCPFGx0/edit?usp=sharing). ## High-level structure -A module contains a sequence of sections. Sections can in general be repeated, but some can occur only once or have dependant sections that must preceed them but not immediately as unknown sections can occur in any order. Each section is identified by an immediate string. Sections whose identity is unknown to the WebAssembly implementation are ignored and this is supported by including the size in bytes for all sections. The encoding of all sections begins as follows: + +The module starts with a magic number and version as follows. + +| Field | Type | Description | +| ----- | ----- | ----- | +| magic number | `uint32 0x6d736100` | Magic number '\0asm' | +| version | `uint32 0xa` | Version 10 | + +This is followed by a sequence of sections. Sections can in general be repeated, but some can occur only once or have dependant sections that must preceed them but not immediately as unknown sections can occur in any order. Each section is identified by an immediate string. Sections whose identity is unknown to the WebAssembly implementation are ignored and this is supported by including the size in bytes for all sections. The encoding of all sections begins as follows: | Field | Type | Description | | ----- | ----- | ----- | -- cgit v1.2.3 From 14952154322a6508cfc2a8eb1942df9a117d8e0e Mon Sep 17 00:00:00 2001 From: Douglas Crosher Date: Sun, 28 Feb 2016 16:13:08 +1100 Subject: Note that the version number will be reset to 1 for MVP. --- BinaryEncoding.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'BinaryEncoding.md') diff --git a/BinaryEncoding.md b/BinaryEncoding.md index 33ca33d..acf874b 100644 --- a/BinaryEncoding.md +++ b/BinaryEncoding.md @@ -79,7 +79,7 @@ The module starts with a magic number and version as follows. | Field | Type | Description | | ----- | ----- | ----- | | magic number | `uint32 0x6d736100` | Magic number '\0asm' | -| version | `uint32 0xa` | Version 10 | +| version | `uint32` | Version number, currently 10. The version for MVP will be reset to 1. | This is followed by a sequence of sections. Sections can in general be repeated, but some can occur only once or have dependant sections that must preceed them but not immediately as unknown sections can occur in any order. Each section is identified by an immediate string. Sections whose identity is unknown to the WebAssembly implementation are ignored and this is supported by including the size in bytes for all sections. The encoding of all sections begins as follows: -- cgit v1.2.3