-
Notifications
You must be signed in to change notification settings - Fork 695
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Specify display conventions for wasm locations #1053
Changes from 1 commit
b9ca72f
a2c18aa
759732f
44f9459
40727c8
fc10e38
2c19e3a
aaa35d0
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. What is the format if there is no URL? Is the field just empty? Is the colon still included? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think there should be something, rather than empty. The note below addresses that, but I agree it's not clear at this line. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Otherwise if it's empty there would be no way to tell different modules apart if they didn't have URLs. Obviously it's still possible to have collisions if the instantiation location is used, but at least it would allow a developer to avoid them if they cared. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Reworded to clarify. |
||
* `${funcIndex}` is an index the [function index space](https://github.com/WebAssembly/design/blob/master/Modules.md#function-index-space). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. typo: index into the ... There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fixed. |
||
* `${pcOffset}` is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, but in this formulation the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Dunno, all I'm saying is this isn't clear. Whichever way works for me. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Switched to more-or-less that wording. I agree it's clearer. |
||
|
||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Function number instead of empty string? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. In a stack trace this would be kind of redundant. e.g. in SpiderMonkey, the full stacktrace entry would be There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. OK I guess this wording is unclear to me. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Reworded to clarify. |
||
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 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/wasm/WebAssembly/g
everywhere.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.