From b9ca72f32482981433e16161ab9d33bf7873dbbb Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Wed, 3 May 2017 10:26:47 -0700 Subject: [PATCH 1/8] Specify display conventions for wasm locations --- Web.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/Web.md b/Web.md index 469d9a5c..e310fafb 100644 --- a/Web.md +++ b/Web.md @@ -123,6 +123,48 @@ MIME type mismatch or `opaque` response types [reject](http://tc39.github.io/ecma262/#sec-rejectpromise) the Promise with a `WebAssembly.CompileError`. +## Developer-facing display conventions + +Browsers, JavaScript engines, and offline tools have common ways of referring to +JavaScript artifacts and language constructs. For example, locations in +JavaScript source code are printed in stack traces or error messages, and are +represented naturally as decimal-format lines and columns in text files. Names +of functions and variables are taken directly from the sources. Therefore (for +example) even though the exact format of Error.stack strings does not always +match, the locations are easily understandable and the same across browsers. + +To achive the same goal of a common representations for WebAssembly constructs, the +following conventions are adopted. + +A wasm location is a reference to a particular instruction in the binary, and may be +displayed by a browser or engine in similar contexts as JavaScript source locations. +It has the following format: +`${url}:wasm-function[${funcIndex}]:0x${pcOffset}` +Where +* `${url}` is the URL associated with the module (e.g. via a response object), if any. +* `${funcIndex}` is an index the [function index space](https://github.com/WebAssembly/design/blob/master/Modules.md#function-index-space). +* `${pcOffset}` is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits. + +Notes: +* The URL field may be interpreted differently depending on the context. For +example offline tools may use a file name; or when the ArrayBuffer-based +`WebAssembly.instantiate` API is used in a browser, it may display the +location of the API call instead. +* Using hexadecimal for module offsets matches common conventions in native tools +such as objdump (where addresses are printed in hex) and makes them visually +distinct from JavaScript line numbers. Other numbers are represented in decimal. + +Names of functions may also be displayed if the module contains a `"name"` +section; these can be used in the same contexts as JavaScript functions. +If there are no names provided, then engines should somehow indicate this; +(it may be sufficient to simply use e.g. an empty string if the name is +immediately adjacent to a wasm location, as its format clearly indicates +that the function is a wasm function). Note also that this document does +not specify the full format of strings such as stack frame representations; +this allows engines to continue using their existing formats for JavaScript +(which existing code may already be depending on) while still printing +wasm frames in a format consistent with JavaScript. + ## Modules WebAssembly's [modules](Modules.md) allow for natural [integration with From a2c18aae8ba5b1624ffd2dc02f6d75fb2e9a8c9d Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Wed, 3 May 2017 11:39:25 -0700 Subject: [PATCH 2/8] s/wasm/WebAssembly --- Web.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Web.md b/Web.md index e310fafb..a060b17b 100644 --- a/Web.md +++ b/Web.md @@ -136,7 +136,7 @@ match, the locations are easily understandable and the same across browsers. To achive the same goal of a common representations for WebAssembly constructs, the following conventions are adopted. -A wasm location is a reference to a particular instruction in the binary, and may be +A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format: `${url}:wasm-function[${funcIndex}]:0x${pcOffset}` @@ -158,12 +158,12 @@ Names of functions may also be displayed if the module contains a `"name"` section; these can be used in the same contexts as JavaScript functions. If there are no names provided, then engines should somehow indicate this; (it may be sufficient to simply use e.g. an empty string if the name is -immediately adjacent to a wasm location, as its format clearly indicates -that the function is a wasm function). Note also that this document does +immediately adjacent to a WebAssembly location, as its format clearly indicates +that the function is a WebAssembly function). Note also that this document does not specify the full format of strings such as stack frame representations; this allows engines to continue using their existing formats for JavaScript (which existing code may already be depending on) while still printing -wasm frames in a format consistent with JavaScript. +WebAssembly frames in a format consistent with JavaScript. ## Modules From 759732f8ebab8cafc78fc215657de2512645aab8 Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Thu, 4 May 2017 10:47:40 -0700 Subject: [PATCH 3/8] review feedback --- Web.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/Web.md b/Web.md index a060b17b..ad073503 100644 --- a/Web.md +++ b/Web.md @@ -139,27 +139,32 @@ following conventions are adopted. A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format: -`${url}:wasm-function[${funcIndex}]:0x${pcOffset}` +`${url}:wasm-function[${funcIndex}]:${pcOffset}` Where -* `${url}` is the URL associated with the module (e.g. via a response object), if any. -* `${funcIndex}` is an index the [function index space](https://github.com/WebAssembly/design/blob/master/Modules.md#function-index-space). -* `${pcOffset}` is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits. +* `${url}` is the URL associated with the module (e.g. via a response + object), or other module identifier (see notes). +* `${funcIndex}` is an index the [function index space](Modules.md#function-index-space). +* `${pcOffset}` is the offset in the module binary of the first byte + of the instruction, printed in hexadecimal with lower-case digits, + with a leading `0x` prefix. Notes: * The URL field may be interpreted differently depending on the context. For example offline tools may use a file name; or when the ArrayBuffer-based `WebAssembly.instantiate` API is used in a browser, it may display the -location of the API call instead. +location of the API call instead. It should not be empty however; a +developer should be able to write their code such that modules from +different sources are displayed with different identifiers. * Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal. Names of functions may also be displayed if the module contains a `"name"` section; these can be used in the same contexts as JavaScript functions. -If there are no names provided, then engines should somehow indicate this; -(it may be sufficient to simply use e.g. an empty string if the name is -immediately adjacent to a WebAssembly location, as its format clearly indicates -that the function is a WebAssembly function). Note also that this document does +If there are no names provided, then engines should simply ensure that +the location can still be identified (e.g. by showing the function +number instead, if the full location is not already being shown). +Note also that this document does not specify the full format of strings such as stack frame representations; this allows engines to continue using their existing formats for JavaScript (which existing code may already be depending on) while still printing From 44f94591bcd58b2669b821aeb54b68900aa5cf5c Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Wed, 10 May 2017 15:26:24 -0700 Subject: [PATCH 4/8] Define module ID instead of URL, prefer module name if present --- Web.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/Web.md b/Web.md index ad073503..a342f353 100644 --- a/Web.md +++ b/Web.md @@ -139,22 +139,27 @@ following conventions are adopted. A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format: -`${url}:wasm-function[${funcIndex}]:${pcOffset}` +`${id}:wasm-function[${funcIndex}]:${pcOffset}` Where -* `${url}` is the URL associated with the module (e.g. via a response - object), or other module identifier (see notes). -* `${funcIndex}` is an index the [function index space](Modules.md#function-index-space). +* `${id}` is an identifier associated with the module (e.g. a URL, + [module name](BinaryEncoding.md#name-section) or other identifier (see notes). +* `${funcIndex}` is an index in the [function index space](Modules.md#function-index-space). * `${pcOffset}` is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits, with a leading `0x` prefix. Notes: -* The URL field may be interpreted differently depending on the context. For -example offline tools may use a file name; or when the ArrayBuffer-based -`WebAssembly.instantiate` API is used in a browser, it may display the -location of the API call instead. It should not be empty however; a -developer should be able to write their code such that modules from -different sources are displayed with different identifiers. +* The ID field may be interpreted differently depending on the +context. If the module has a name section with a +[module name](BinaryEncoding.md#name-section), that should be +preferred. Otherwise, there are several possiblities: offline tools +may use a file name; when the response-based +instantiation [API](#additional-web-embedding-api) is used in a +browser, the associated URL should be used; +or when the ArrayBuffer-based instantiation +[API](JS.md#webassembly-instantiate) is used, the browser may use its best +effort at showing the location of the API call instead (this may be imprecise, +e.g. if the call is part of JS code evaluated with `eval`). * Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal. From 40727c8188cc36de6ea8a4cfa2e68820790b0007 Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Thu, 11 May 2017 15:25:57 -0700 Subject: [PATCH 5/8] use URL and module_name.function_name --- Web.md | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/Web.md b/Web.md index a342f353..a6339cb3 100644 --- a/Web.md +++ b/Web.md @@ -139,36 +139,42 @@ following conventions are adopted. A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format: -`${id}:wasm-function[${funcIndex}]:${pcOffset}` +`${url}:wasm-function[${funcIndex}]:${pcOffset}` Where -* `${id}` is an identifier associated with the module (e.g. a URL, - [module name](BinaryEncoding.md#name-section) or other identifier (see notes). +* `${url}` is the URL associated with the module, if applicable (see notes). * `${funcIndex}` is an index in the [function index space](Modules.md#function-index-space). * `${pcOffset}` is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits, with a leading `0x` prefix. Notes: -* The ID field may be interpreted differently depending on the -context. If the module has a name section with a -[module name](BinaryEncoding.md#name-section), that should be -preferred. Otherwise, there are several possiblities: offline tools -may use a file name; when the response-based +* The URL field may be interpreted differently depending on the +context. For example, offline tools may use a filename instead. +When the response-based instantiation [API](#additional-web-embedding-api) is used in a -browser, the associated URL should be used; -or when the ArrayBuffer-based instantiation -[API](JS.md#webassembly-instantiate) is used, the browser may use its best -effort at showing the location of the API call instead (this may be imprecise, -e.g. if the call is part of JS code evaluated with `eval`). +browser, the associated URL should be used; or when the +ArrayBuffer-based instantiation +[API](JS.md#webassembly-instantiate) is used, the browser should represent +the location of the API call. This representation should be consistent with how +the browser otherwise represents JavaScript locations; this will necessarily +handle corner cases such as code evaluated with `eval`, and will differ between +browsers. * Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal. -Names of functions may also be displayed if the module contains a `"name"` -section; these can be used in the same contexts as JavaScript functions. -If there are no names provided, then engines should simply ensure that -the location can still be identified (e.g. by showing the function -number instead, if the full location is not already being shown). +Names of functions may also be displayed if the module contains a +["name" section](BinaryEncoding.md#name-section); +these can be used in the same contexts as JavaScript functions. +If the module's name section includes both module and function names, it +should be represented as `${module_name}.${function_name}`. +If the function name is absent, then the output can be context-dependent. +For example, if the function name is shown alongside its location in a +stack trace, then just the module name (if present) or an empty string +can be used, because the function index is shown with the location. +Otherwise a representation that indicates the function index should be +used. + Note also that this document does not specify the full format of strings such as stack frame representations; this allows engines to continue using their existing formats for JavaScript From fc10e3814b36dd53b8cf8bd96a49eae22d3fa7d6 Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Fri, 12 May 2017 10:30:19 -0700 Subject: [PATCH 6/8] Clarify eval analogy with examples, refine name display and add example --- Web.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/Web.md b/Web.md index a6339cb3..ede56664 100644 --- a/Web.md +++ b/Web.md @@ -149,16 +149,19 @@ Where Notes: * The URL field may be interpreted differently depending on the -context. For example, offline tools may use a filename instead. -When the response-based +context. When the response-based instantiation [API](#additional-web-embedding-api) is used in a browser, the associated URL should be used; or when the ArrayBuffer-based instantiation [API](JS.md#webassembly-instantiate) is used, the browser should represent -the location of the API call. This representation should be consistent with how -the browser otherwise represents JavaScript locations; this will necessarily -handle corner cases such as code evaluated with `eval`, and will differ between -browsers. +the location of the API call. This kind of instantiation is analagous to +executing JavaScript using `eval`; therefore if the browser has an existing +method to represent the location of the `eval` call it can use a similar +one for `WebAssembly.instantiate`. For example if the browser uses +`foo.js line 10 > eval` or `(eval at bar (foo.js:10:3)` for `eval`, it could +use `foo.js line 10 > WebAssembly.instantiate` or +`(WebAssembly.instantiate at bar (foo.js:10:3)`, respectively. +Offline tools may use a filename instead. * Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal. @@ -173,7 +176,7 @@ For example, if the function name is shown alongside its location in a stack trace, then just the module name (if present) or an empty string can be used, because the function index is shown with the location. Otherwise a representation that indicates the function index should be -used. +used (for example `${module_name}.wasm-function[${funcIndex}]`). Note also that this document does not specify the full format of strings such as stack frame representations; From 2c19e3ad64efedfbf5695f66784cb17ac0e4a0bf Mon Sep 17 00:00:00 2001 From: Derek Schuff Date: Fri, 12 May 2017 11:24:54 -0700 Subject: [PATCH 7/8] fix copypasta, link, formatting --- Web.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Web.md b/Web.md index ede56664..363a8d69 100644 --- a/Web.md +++ b/Web.md @@ -139,7 +139,9 @@ following conventions are adopted. A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format: + `${url}:wasm-function[${funcIndex}]:${pcOffset}` + Where * `${url}` is the URL associated with the module, if applicable (see notes). * `${funcIndex}` is an index in the [function index space](Modules.md#function-index-space). @@ -153,14 +155,14 @@ context. When the response-based instantiation [API](#additional-web-embedding-api) is used in a browser, the associated URL should be used; or when the ArrayBuffer-based instantiation -[API](JS.md#webassembly-instantiate) is used, the browser should represent +[API](JS.md#webassemblyinstantiate) is used, the browser should represent the location of the API call. This kind of instantiation is analagous to executing JavaScript using `eval`; therefore if the browser has an existing method to represent the location of the `eval` call it can use a similar one for `WebAssembly.instantiate`. For example if the browser uses -`foo.js line 10 > eval` or `(eval at bar (foo.js:10:3)` for `eval`, it could +`foo.js line 10 > eval` or `eval at bar (foo.js:10:3)` for `eval`, it could use `foo.js line 10 > WebAssembly.instantiate` or -`(WebAssembly.instantiate at bar (foo.js:10:3)`, respectively. +`WebAssembly.instantiate at bar (foo.js:10:3)`, respectively. Offline tools may use a filename instead. * Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually From aaa35d0fbd038f8b21ee69584a4bdc6b885f592d Mon Sep 17 00:00:00 2001 From: Luke Wagner Date: Thu, 18 May 2017 18:14:29 -0500 Subject: [PATCH 8/8] Address review comment --- Web.md | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/Web.md b/Web.md index 363a8d69..4c6fbeef 100644 --- a/Web.md +++ b/Web.md @@ -168,23 +168,26 @@ Offline tools may use a filename instead. such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal. -Names of functions may also be displayed if the module contains a -["name" section](BinaryEncoding.md#name-section); -these can be used in the same contexts as JavaScript functions. -If the module's name section includes both module and function names, it -should be represented as `${module_name}.${function_name}`. -If the function name is absent, then the output can be context-dependent. -For example, if the function name is shown alongside its location in a -stack trace, then just the module name (if present) or an empty string -can be used, because the function index is shown with the location. -Otherwise a representation that indicates the function index should be -used (for example `${module_name}.wasm-function[${funcIndex}]`). - -Note also that this document does -not specify the full format of strings such as stack frame representations; -this allows engines to continue using their existing formats for JavaScript -(which existing code may already be depending on) while still printing -WebAssembly frames in a format consistent with JavaScript. +While the `name` property of [exported WebAssembly functions](JS.md#exported-function-exotic-objects) +is specified by the JS API, synthesized function names are also +displayed in other contexts like devtool callstacks and `Error.stack`. +If a WebAssembly module contains a ["name" section](BinaryEncoding.md#name-section), +these names should be used to synthesize a function name as follows: +* If a function name subsection is present, the displayed name should + be `${module_name}.${function_name}` or `${function_name}`, depending + on whether the module name is present. +* Otherwise, the output can be context-dependent: + * If the function name is shown alongside its location in a + stack trace, then just the module name (if present) or an empty string + can be used (because the function index is already in the location). + * Otherwise, `${module_name}.wasm-function[${funcIndex}]` or + `wasm-function[${funcIndex}]` should be used to convey the function index. + +Note that this document does not specify the full format of strings such as +stack frame representations; this allows engines to continue using their +existing formats for JavaScript (which existing code may already be depending +on) while still printing WebAssembly frames in a format consistent with +JavaScript. ## Modules