diff --git a/document/appendix-names/index.rst b/document/appendix-names/index.rst deleted file mode 100644 index 6c8fe7a20b..0000000000 --- a/document/appendix-names/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -Appendix: Name Section ----------------------- - -.. todo:: - - Describe diff --git a/document/appendix-properties/index.rst b/document/appendix-properties/index.rst deleted file mode 100644 index d43f7ccf99..0000000000 --- a/document/appendix-properties/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -Appendix: Formal Properties ---------------------------- - -.. todo:: - - Describe and sketch proof (progress, preservation, uniqueness) diff --git a/document/appendix-algorithm/index.rst b/document/appendix/algorithm.rst similarity index 59% rename from document/appendix-algorithm/index.rst rename to document/appendix/algorithm.rst index 883daeb7db..48797273eb 100644 --- a/document/appendix-algorithm/index.rst +++ b/document/appendix/algorithm.rst @@ -1,5 +1,5 @@ -Appendix: Validation Algorithm ------------------------------- +Validation Algorithm +-------------------- .. todo:: diff --git a/document/appendix/implementation.rst b/document/appendix/implementation.rst new file mode 100644 index 0000000000..2513fa1130 --- /dev/null +++ b/document/appendix/implementation.rst @@ -0,0 +1,137 @@ +.. _impl: +.. index:: ! implementation limitations, implementation + +Implementation Limitations +-------------------------- + +Implementations typically impose additional restrictions on a number of aspects of a WebAssembly module or execution. +These may stem from: + +* physical resource limits, +* constraints imposed by the embedder or its environment, +* limitations of selected implementation strategies. + +This section lists allowed limitations. +Where restrictions take the form of numeric limits, no minimum requirements are given, +nor are the limits assumed to be concrete, fixed numbers. +However, it is expected that all implementations have "reasonably" large limits to enable common applications. + +.. note:: + A conforming implementation is not allowed to leave out individual *features*. + However, designated subsets of WebAssembly may be specified in the future. + + +Syntactic Limits +~~~~~~~~~~~~~~~~ + +.. _impl-syntax: +.. index:: abstract syntax, module, type, function, table, memory, global, element, data, import, export, parameter, result, local, structured control instruction, instruction, name, Unicode, code point + +Structure +......... + +An implementation may impose restrictions on the following dimensions of a module: + +* the number of :ref:`types ` in a :ref:`module ` +* the number of :ref:`functions ` in a :ref:`module `, including imports +* the number of :ref:`tables ` in a :ref:`module `, including imports +* the number of :ref:`memories ` in a :ref:`module `, including imports +* the number of :ref:`globals ` in a :ref:`module `, including imports +* the number of :ref:`element segments ` in a :ref:`module ` +* the number of :ref:`data segments ` in a :ref:`module ` +* the number of :ref:`imports ` to a :ref:`module ` +* the number of :ref:`exports ` form a :ref:`module ` +* the number of parameters in a :ref:`function type ` +* the number of results in a :ref:`function type ` +* the number of :ref:`locals ` in a :ref:`function ` +* the size of a :ref:`function ` body +* the size of a :ref:`structured control instruction ` +* the number of :ref:`structured control instructions ` in a :ref:`function ` +* the nesting depth of :ref:`structured control instructions ` +* the number of :ref:`label indices ` in a |brtable| instruction +* the length of an :ref:`element segment ` +* the length of a :ref:`data segment ` +* the length of a :ref:`name ` +* the range of :ref:`code points ` in a :ref:`name ` + +If the limits of an implementation are exceeded for a given module, +then the implementation may reject the :ref:`validation `, compilation, or :ref:`instantiation ` of that module with an embedder-specific error. + +.. note:: + The last item allows embedders that operate in limited environments without support for + `Unicode `_ to limit the + names of :ref:`imports ` and :ref:`exports ` + to common subsets like `ASCII `_. + + +.. _impl-binary: +.. index:: binary format, module, section, function, code + +Binary Format +............. + +For a module given in :ref:`binary format `, additional limitations may be imposed on the following dimensions: + +* the size of a :ref:`module ` +* the size of any :ref:`section ` +* the size of an individual :ref:`function's code ` +* the number of :ref:`sections ` + + +.. _impl-text: +.. index:: text format, source text, token, identifier, character, unicode + +Text Format +........... + +For a module given in :ref:`text format `, additional limitations may be imposed on the following dimensions: + +* the size of the :ref:`source text ` +* the size of any syntactic element +* the size of an individual :ref:`token ` +* the nesting depth of :ref:`folded instructions ` +* the length of symbolic :ref:`identifiers ` +* the range of literal :ref:`characters ` (code points) allowed in the :ref:`source text ` + + +.. _impl-valid: +.. index:: validation, function + +Validation +~~~~~~~~~~ + +An implementation may defer :ref:`validation ` of individual :ref:`functions ` until they are first :ref:`invoked `. + +If a function turns out to be invalid, then the invocation, and every consecutive call to the same function, results in a :ref:`trap `. + +.. note:: + This is to allow implementations to use interpretation or just-in-time compilation for functions. + The function must still be fully validated before execution of its body begins. + + +.. _impl-exec: +.. index:: execution, module instance, function instance, table instance, memory instance, global instance, allocation, frame, label, value + +Execution +~~~~~~~~~ + +Restrictions on the following dimensions may be imposed during :ref:`execution ` of a WebAssembly program: + +* the number of allocated :ref:`module instances ` +* the number of allocated :ref:`function instances ` +* the number of allocated :ref:`table instances ` +* the number of allocated :ref:`memory instances ` +* the number of allocated :ref:`global instances ` +* the size of a :ref:`table instance ` +* the size of a :ref:`memory instance ` +* the number of :ref:`frames ` on the :ref:`stack ` +* the number of :ref:`labels ` on the :ref:`stack ` +* the number of :ref:`values ` on the :ref:`stack ` + +If the runtime limits of an implementation are exceeded during execution of a computation, +then it may terminate that computation and report an embedder-specific error to the invoking code. + +Some of the above limits may already be verified during instantiation, in which case an implementation may report exceedance in the same manner as for :ref:`syntactic limits `. + +.. note:: + Concrete limits are usually not fixed but may be dependent on specifics, interdependent, vary over time, or depend on other implementation- or embedder-specific situations or events. diff --git a/document/appendix/index.rst b/document/appendix/index.rst new file mode 100644 index 0000000000..628e859994 --- /dev/null +++ b/document/appendix/index.rst @@ -0,0 +1,12 @@ +.. _appendix: + +Appendix +======== + +.. toctree:: + :maxdepth: 2 + + implementation + names + properties + algorithm diff --git a/document/appendix/names.rst b/document/appendix/names.rst new file mode 100644 index 0000000000..a203ce2ded --- /dev/null +++ b/document/appendix/names.rst @@ -0,0 +1,6 @@ +Name Section +------------ + +.. todo:: + + Describe diff --git a/document/appendix/properties.rst b/document/appendix/properties.rst new file mode 100644 index 0000000000..5d0acdaaae --- /dev/null +++ b/document/appendix/properties.rst @@ -0,0 +1,8 @@ +Formal Properties +----------------- + +.. todo:: + + * representation (bijection between abstract and binary) + * validation (progress, preservation) + * ... diff --git a/document/index.rst b/document/index.rst index 6b29eefc1f..2554ac2509 100644 --- a/document/index.rst +++ b/document/index.rst @@ -14,9 +14,7 @@ WebAssembly Specification execution/index binary/index text/index - appendix-properties/index - appendix-algorithm/index - appendix-names/index + appendix/index .. only:: latex