diff --git a/FAQ.md b/FAQ.md index 5e0a8406..42fefcfd 100644 --- a/FAQ.md +++ b/FAQ.md @@ -90,7 +90,7 @@ even before there is any native support. As explained in the [high-level goals](HighLevelGoals.md), to achieve a Minimum Viable Product, the initial focus is on [C/C++](CAndC++.md). -However, by [integrating with JS at the ES6 Module interface](MVP.md#modules), +However, by [integrating with JS at the ES6 Module interface](Modules.md#integration-with-es6-modules), web developers don't need to write C++ to take advantage of libraries that others have written; reusing a modular C++ library can be as simple as [using a module from JS](http://jsmodules.io). diff --git a/MVP.md b/MVP.md index afc15f2f..36fdadf3 100644 --- a/MVP.md +++ b/MVP.md @@ -11,84 +11,15 @@ even on mobile devices, which leads to roughly the same functionality as This document explains the contents of the MVP at a high-level. There are also separate docs with more precise descriptions of: + * [Modules](Modules.md) * [Polyfill to JavaScript](Polyfill.md); * [AST semantics](AstSemantics.md); * [Binary encoding](BinaryEncoding.md); + * [Text format](TextFormat.md); * Implementation [in the browser](Web.md) and [outside the browser](NonWeb.md). **Note**: This content is still in flux and open for discussion. -## Modules - -* The primary unit of loadable, executable code is a **module**. -* A module can declare a subset of its functions and global variables to be - **exports**. The meaning of exports (how and when they are called) is defined - by the host environment. For example, `_start` and `init` can be the only - meaningful exports. -* A module can declare a set of **imports**. An import is a tuple containing a - module name, export name, and the type to use for the import within the - module. The host environment controls the mapping from module name to which - module is loaded. -* The spec defines the semantics of loading and calling exports of a *single* - module. The meaning of a call to an import is defined by the host environment. - * In a minimal shell environment, imports could be limited to builtin modules - (implemented by the shell) and/or shell scripts. - * The [dynamic linking](FutureFeatures.md#dynamic-linking) post-MVP feature - would extend the semantics to include multiple modules and thus allow sharing -linear memory and pointers. Dynamic linking would be semantically distinct from - importing, however. -* When compiling from C++, imports would be generated for unresolved `extern` - functions and calls to those `extern` functions would call the import. -* Host environments can define builtin modules that are implemented natively but - can otherwise be imported like [other modules](MVP.md#modules). As examples: - * A WebAssembly shell might define a builtin `stdio` library with an export - `puts`. - * In the browser, the WebIDL support mentioned in - [future features](FutureFeatures.md). -* Any [ABI](https://en.wikipedia.org/wiki/Application_binary_interface) for - statically linked libraries will be specific to your source language compiler. - In the future, [standard ABIs may be defined](FutureFeatures.md#dynamic-linking) - to allow for compatibility between compilers and versions of compilers. -* **TODO**: there is more to discuss here concerning APIs. - -## Module structure - -* At the top level, a module is ELF-like: a sequence of sections which declare - their type and byte-length. - * Sections with unknown types would be skipped without error. - * Standardized section types: - * module import section; - * globals section (constants, signatures, variables); - * code section; - * memory initialization section. - -## Code section - -* The code section begins with a table of functions containing the signatures - and offsets of each function followed by the list of function bodies. This - allows parallel and streaming decoding, validation and compilation. - * A function body consists of a set of typed variable bindings and an AST - closed under these bindings. - * The [Abstract Syntax Tree](AstSemantics.md) is composed of two primary kinds - of nodes: statements and expressions. - * [Control flow](AstSemantics.md#control-flow-structures) is structured (no - `goto`). - -## Binary format - -* A [binary format](BinaryEncoding.md) provides efficiency: it reduces download - size and accelerates decoding, thus enabling even very large codebases to have - quick startup times. Towards that goal, the binary format will be natively - decoded by browsers. -* The binary format has an equivalent and isomorphic - [text format](MVP.md#text-format). Conversion from one format to the other is - both straightforward and causes no loss of information in either direction. - -## Text format - -The [text format](TextFormat.md) provides readability to developers, and is -isomorphic to the [binary format](BinaryEncoding.md). - ## Linear Memory * In the MVP, when a WebAssembly module is loaded, it creates a new linear memory which @@ -105,6 +36,21 @@ isomorphic to the [binary format](BinaryEncoding.md). detaches any existent `ArrayBuffer`. * See the [AST Semantics linear memory section](AstSemantics.md#linear-memory) for more details. + +## Binary format + +* A [binary format](BinaryEncoding.md) provides efficiency: it reduces download + size and accelerates decoding, thus enabling even very large codebases to have + quick startup times. Towards that goal, the binary format will be natively + decoded by browsers. +* The binary format has an equivalent and isomorphic + [text format](MVP.md#text-format). Conversion from one format to the other is + both straightforward and causes no loss of information in either direction. + +## Text format + +The [text format](TextFormat.md) provides readability to developers, and is +isomorphic to the [binary format](BinaryEncoding.md). ## Security diff --git a/Modules.md b/Modules.md new file mode 100644 index 00000000..dc5a8976 --- /dev/null +++ b/Modules.md @@ -0,0 +1,127 @@ +# Modules + +The distributable, loadable, and executable unit of code in WebAssembly +is called a **module**. A module contains: +* a set of [imports and exports](Modules.md#imports-and-exports); +* a section defining the [initial state of linear memory](Modules.md#initial-state-of-linear-memory); +* a section containing [code](Modules.md#code-section); +* after the MVP, sections containing [debugging/symbol information](Tooling.md) or + a reference to separate files containing them; and +* possibly other sections in the future. +Sections declare their type and byte-length. Sections with unknown types are +silently ignored. + +While WebAssembly modules are designed to interoperate with ES6 modules +in a Web environment (more details [below](Modules.md#integration-with-es6-modules)), +WebAssembly modules are defined independently of JavaScript and do not require +the host environment to include a JavaScript VM. + +## Imports and Exports + +A module defines a set of functions in its +[code section](Modules.md#code-section) and can declare and name a subset of +these functions to be **exports**. The meaning of exports (how and when they are +called) is defined by the host environment. For example, a minimal shell +environment might only probe for and call a `_start` export when given a module +to execute. + +A module can declare a set of **imports**. An import is a tuple containing a +module name, the name of an exported function to import from the named module, +and the signature to use for that import within the importing module. Within a +module, the import can be [directly called](AstSemantics.md#calls) like a +function (according to the signature of the import). When the imported +module is also WebAssembly, it would be an error if the signature of the import +doesn't match the signature of the export. + +The WebAssembly spec does not define how imports are interpreted: +* the host environment can interpret the module name as a file path, a URL, + a key in a fixed set of builtin modules or the host environment may invoke a + user-defined hook to resolve the module name to one of these; +* the module name does not need to resolve to a WebAssembly module; it + could resolve to a builtin module (implemented by the host environment) or a + module written in another, compatible language; and +* the meaning of calling an imported function is host-defined. + +The open-ended nature of module imports allow them to be used to expose +arbitrary host environment functionality to WebAssembly code, similar to a +native `syscall`. For example, a shell environment could define a builtin +`stdio` module with an export `puts`. + +In C/C++, an undefined `extern` declaration (perhaps only when given the +magic `__attribute__` or declared in a separate list of imports) could be +compiled to an import and C/C++ calls to this `extern` would then be compiled +to calls to this import. This is one way low-level C/C++ libraries could call +out of WebAssembly in order to implement portable source-level interfaces +(e.g., POSIX, OpenGL or SDL) in terms of host-specific functionality. + +### Integration with ES6 modules + +While ES6 defines how to parse, link and execute a module, ES6 does not +define when this parsing/linking/execution occurs. An additional extension +to the HTML spec is required to say when a script is parsed as a module instead +of normal global code. This work is [ongoing](http://TODO:link-to-loader-level-0-repo). +Currently, the following entry points for modules are being considered: +* `