Skip to content

Add a toolchain-independent ABI document, and propose _initialize #203

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Oct 16, 2024
Merged

Add a toolchain-independent ABI document, and propose _initialize #203

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
19a35b8
Add a toolchain-independent ABI document, and propose `_initialize`
sunfishcode Mar 6, 2023
710ec66
Rename to "Basic Module ABI".
sunfishcode Mar 7, 2023
875879d
Update BasicModuleABI.md
sunfishcode Mar 7, 2023
8e07360
Explain when we can and can't use the wasm start function.
sunfishcode Mar 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions BasicModuleABI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
Basic Module ABI
================

There are many different ways to use Wasm modules, and many different
conventions, language-specific ABIs, and toolchain-specific ABIs. This
document describes ABI features intended to be common across all ABIs.

## The `_initialize` function

If a module exports a function named `_initialize` with no arguments and no
return values, and does not export a function named `_start`, the toolchain
that produced my assume that on any instance of the module, this `_initialize`
function is called before any other exports are accessed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what's the relationship with similar functions like __wasm_call_ctors?
eg. which one to call if multiple of them are exported?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know, and indeed, it may be too late to try to design anything, to avoid breaking existing setups.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The _initialize and _start functions are in charge of calling __wasm_call_ctors.

I see __wasm_call_ctors as an llvm-internal function which is not designed to be called directly by users but instead by higher level toolchain functions like _start and _initialize (or other crt1-type functions).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure. but there are existing conventions to call exported __wasm_call_ctors.
eg. https://github.com/emscripten-core/emscripten/blob/bec42dac7873903d09d713963e34020c22a8bd2d/src/library_dylink.js#L846

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, that is because emscripten does it own thing here and basically implements _start / _initialize in JavaScript. I wouldn't worry about this case since emscripten only ever loads modules that is builds itself.. we may convert to using a more standards-based approach in the future, but for now emscripten-built wasm modules are fairly specific to emscripten.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other words, the standard-based way to go is to export either _start or _initialize. Exporting and directly calling main and/or __wasm_call_ctors (as emscripten does) is non-standard.

It would also be non-standard/undefined, for example, to call __wasm_call_ctors directly from user C/C++ code.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so, the standard thing suggested here is to ignore __wasm_call_ctors __post_instantiate etc even if they are exported, and only cares _initialize? (besides that, _start in case of wasi)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would make sense to me yes.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok. it makes sense to me too.


This is intended to support language features such as C++ static constructors,
as well as "top-level scripts" in many scripting languages, which can't use
the [wasm start function] because they may call imports that need to access
the module's exports. In use cases that don't need this, the wasm start
function should be used.

[wasm start section]: https://webassembly.github.io/spec/core/syntax/modules.html#syntax-start