Skip to content

Commit

Permalink
Merge branch 'main' into wasm-3.0
Browse files Browse the repository at this point in the history
  • Loading branch information
rossberg committed Nov 7, 2024
2 parents 5f2f99d + 268a03d commit 87789ff
Show file tree
Hide file tree
Showing 13 changed files with 265 additions and 78 deletions.
6 changes: 3 additions & 3 deletions .github/workflows/ci-interpreter.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,15 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
- name: Setup OCaml
uses: ocaml/setup-ocaml@v2
uses: ocaml/setup-ocaml@v3
with:
ocaml-compiler: 4.14.x
- name: Setup OCaml tools
run: opam install --yes ocamlfind.1.9.5 js_of_ocaml.4.0.0 js_of_ocaml-ppx.4.0.0
- name: Setup Node.js
uses: actions/setup-node@v2
uses: actions/setup-node@v4
with:
node-version: 20.x
- name: Build interpreter
Expand Down
14 changes: 7 additions & 7 deletions .github/workflows/ci-spec.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
with:
submodules: "recursive"
- name: Setup Node.js
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: 16
- name: Setup Bikeshed
Expand All @@ -44,7 +44,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
- name: Setup Bikeshed
run: pip install bikeshed && bikeshed update
- name: Run Bikeshed
Expand All @@ -59,7 +59,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
- name: Setup Bikeshed
run: pip install bikeshed && bikeshed update
- name: Run Bikeshed
Expand Down Expand Up @@ -128,7 +128,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
Expand All @@ -147,7 +147,7 @@ jobs:
- build-spec-versions
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
- name: Create output directory
run: mkdir _output && cp document/index.html _output/index.html
- name: Download core spec artifact
Expand Down Expand Up @@ -187,7 +187,7 @@ jobs:
path: _output/versions
- name: Publish to GitHub Pages
if: github.ref == 'refs/heads/main'
uses: peaceiris/actions-gh-pages@v3
uses: peaceiris/actions-gh-pages@v4
with:
publish_dir: ./_output
github_token: ${{ secrets.GITHUB_TOKEN }}
33 changes: 25 additions & 8 deletions .github/workflows/w3c-publish.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
name: Publish to W3C TR space
name: Validate/Publish to W3C TR space

on:
push:
branches: [ main ]
paths: [ .github/**, document/** ]
pull_request:
paths: [ .github/**, document/** ]

# Allows you to run this workflow manually from the Actions tab, gh CLI tool,
# or REST API. THe w3c-status options correspond to the valid options for
Expand All @@ -23,30 +25,45 @@ on:
- CRD
- CR

env:
YARN_ENABLE_IMMUTABLE_INSTALLS: false
W3C_STATUS: ${{ github.event_name == 'workflow_dispatch' && inputs.w3c-status || 'WD' }}

jobs:
publish-to-w3c-TR:
if: github.repository == 'WebAssembly/spec'
strategy:
fail-fast: false
matrix:
spec: [core, js-api, web-api]
runs-on: ubuntu-latest
steps:
- name: Checkout repo
uses: actions/checkout@v2
uses: actions/checkout@v4
with:
submodules: "recursive"
- name: Setup Node.js
uses: actions/setup-node@v3
uses: actions/setup-node@v4
with:
node-version: 16
- name: Setup Bikeshed
run: pip install bikeshed && bikeshed update
- name: Setup TexLive
if: ${{ matrix.spec == 'core' }}
run: sudo apt-get update -y && sudo apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
- name: Setup Sphinx
if: ${{ matrix.spec == 'core' }}
run: pip install six && pip install sphinx==5.1.0
- name: Publish all specs to their https://www.w3.org/TR/ URLs
run: cd document && make -e WD-echidna-CI
- name: Publish ${{ matrix.spec }} spec to its https://www.w3.org/TR/ URL
if: env.W3C_ECHIDNA_TOKEN_CORE
run: cd document && make -e -C ${{ matrix.spec }} WD-echidna-CI
env:
W3C_STATUS: ${{ github.event_name == 'push' && 'CRD' || inputs.w3c-status }}
W3C_ECHIDNA_TOKEN_CORE: ${{ secrets.W3C_ECHIDNA_TOKEN_CORE }}
W3C_ECHIDNA_TOKEN_JSAPI: ${{ secrets.W3C_ECHIDNA_TOKEN_JSAPI }}
W3C_ECHIDNA_TOKEN_WEBAPI: ${{ secrets.W3C_ECHIDNA_TOKEN_WEBAPI }}
YARN_ENABLE_IMMUTABLE_INSTALLS: false
ECHIDNA_DRYRUN: ${{ !(github.event_name == 'push' && github.repository == 'WebAssembly/spec' && github.ref == 'refs/heads/main') }}
- name: Validate ${{ matrix.spec }} spec with Echidna
if: env.W3C_USERNAME
run: cd document && make -e -C ${{ matrix.spec }} WD-echidna
env:
W3C_USERNAME: ${{ secrets.W3C_USERNAME }}
W3C_PASSWORD: ${{ secrets.W3C_PASSWORD }}
13 changes: 9 additions & 4 deletions document/core/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ NAME = WebAssembly
DECISION_URL = https://github.com/WebAssembly/meetings/blob/main/main/2024/WG-06-12.md
TAR = tar
DEADLINE = $(shell date -d "+30 days" +%Y-%m-%d 2>/dev/null || date -v +30d +%Y-%m-%d)
ECHIDNA_DRYRUN = true

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
Expand Down Expand Up @@ -196,9 +197,11 @@ WD-echidna: WD-tar
curl 'https://labs.w3.org/echidna/api/request' \
--user '$(W3C_USERNAME):$(W3C_PASSWORD)' \
-F "tar=@$(BUILDDIR)/WD.tar" \
-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
-F "decision=$(DECISION_URL)" \
-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
python3 ../util/check-echidna-status.py $(BUILDDIR)
@echo
@echo "Published $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"

.PHONY: WD-echidna-CI
WD-echidna-CI: WD-tar
Expand All @@ -210,9 +213,11 @@ WD-echidna-CI: WD-tar
curl 'https://labs.w3.org/echidna/api/request' \
-F "tar=@$(BUILDDIR)/WD.tar" \
-F "token=$(W3C_ECHIDNA_TOKEN_CORE)" \
-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
-F "decision=$(DECISION_URL)" \
-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
python3 ../util/check-echidna-status.py $(BUILDDIR)
@echo
@echo "Published $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"

.PHONY: diff
diff: bikeshed
Expand Down
2 changes: 1 addition & 1 deletion document/core/exec/modules.rst
Original file line number Diff line number Diff line change
Expand Up @@ -447,7 +447,7 @@ and list of :ref:`reference <syntax-ref>` vectors for the module's :ref:`element

24. Let :math:`\exportinst^\ast` be the concatenation of the :ref:`export instances <syntax-exportinst>` :math:`\exportinst_i` in index order.

25. Let :math:`\moduleinst` be the :ref:`module instance <syntax-moduleinst>` :math:`\{\MITYPES~\deftype^\ast,` :math:`\MIFUNCS~\funcaddr_{\F{mod}}^\ast,` :math:`\MITABLES~\tableaddr_{\F{mod}}^\ast,` :math:`\MIMEMS~\memaddr_{\F{mod}}^\ast,` :math:`\MIGLOBALS~\globaladdr_{\F{mod}}^\ast,` :math:`\MITAGS~\tagaddr_{\F{mod}}^\ast`, :math:`\MIEXPORTS~\exportinst^\ast\}`.
25. Let :math:`\moduleinst` be the :ref:`module instance <syntax-moduleinst>` :math:`\{\MITYPES~\deftype^\ast,` :math:`\MIFUNCS~\funcaddr_{\F{mod}}^\ast,` :math:`\MITABLES~\tableaddr_{\F{mod}}^\ast,` :math:`\MIMEMS~\memaddr_{\F{mod}}^\ast,` :math:`\MIGLOBALS~\globaladdr_{\F{mod}}^\ast,` :math:`\MITAGS~\tagaddr_{\F{mod}}^\ast`, :math:`\MIELEMS~\elemaddr^\ast,` :math:`\MIDATAS~\dataaddr^\ast,` :math:`\MIEXPORTS~\exportinst^\ast\}`.

26. Return :math:`\moduleinst`.

Expand Down
24 changes: 6 additions & 18 deletions document/core/util/bikeshed_fixup.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,7 @@
def Main():
data = open(sys.argv[1]).read()

# Make bikeshed happy
# Apparently it can't handle empty line before DOCTYPE comment
data = data.replace('\n<!DOCTYPE', '<!DOCTYPE')
# Ensure newline before <pre>
data = data.replace('<pre>', '\n<pre>')
# Clean up the input for Bikeshed

# Don't add more than 3 levels to TOC.
data = data.replace('<h5>', '<h5 class="no-toc">')
Expand All @@ -34,7 +30,8 @@ def Main():
'Validation Algorithm',
'Custom Sections',
'Soundness',
'Changes',
'Type System Properties',
'Change History',
'Index of Types',
'Index of Instructions',
'Index of Semantic Rules']:
Expand All @@ -43,18 +40,6 @@ def Main():
'<h3>A.' + str(number) + ' ' + section + '</h3>')
number += 1


# Drop spurious navigation.
data = data.replace(
"""
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="nav-item nav-item-0"><a href="#">WebAssembly 1.1</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">WebAssembly 1.1</a></li>
</ul>
</div> """, '')

# Use bikeshed biblio references for unicode and IEEE754
data = data.replace(
"""<a class="reference external" href="https://www.unicode.org/versions/latest/">Unicode</a>""",
Expand Down Expand Up @@ -88,6 +73,9 @@ def Main():
r'\1',
data, flags=re.DOTALL)

# Escape some latex sequences that Bikeshed interprets as macros
data = data.replace(r' \\[1ex]', r' \&#x5c;\[1ex]')

sys.stdout.write(data)

Main()
14 changes: 10 additions & 4 deletions document/js-api/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ NAME = WebAssembly
DECISION_URL = https://github.com/WebAssembly/meetings/blob/main/main/2024/WG-06-12.md
TAR = tar
DEADLINE = $(shell date -d "+30 days" +%Y-%m-%d 2>/dev/null || date -v +30d +%Y-%m-%d)
ECHIDNA_DRYRUN = true

.PHONY: all
all:
Expand Down Expand Up @@ -35,7 +36,6 @@ diff: all
# macOS tar has no “--transform” option (only GNU tar does), so on macOS,
# do “brew install tar” & run “make” like this: “TAR=gtar make -e WD-tar”
WD-tar: all
bikeshed spec --md-status=$(W3C_STATUS) --md-deadline=$(DEADLINE) index.bs $(BUILDDIR)/html/index.html
$(TAR) -C $(BUILDDIR)/html --transform="s/index.html/Overview.html/" -cf $(BUILDDIR)/WD.tar index.html
@echo "Built $(BUILDDIR)/WD.tar."

Expand All @@ -50,7 +50,11 @@ WD-echidna: WD-tar
curl 'https://labs.w3.org/echidna/api/request' \
--user '$(W3C_USERNAME):$(W3C_PASSWORD)' \
-F "tar=@$(BUILDDIR)/WD.tar" \
-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
-F "decision=$(DECISION_URL)" \
-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
python3 ../util/check-echidna-status.py $(BUILDDIR)
@echo
@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"

.PHONY: WD-echidna-CI
WD-echidna-CI: WD-tar
Expand All @@ -62,6 +66,8 @@ WD-echidna-CI: WD-tar
curl 'https://labs.w3.org/echidna/api/request' \
-F "tar=@$(BUILDDIR)/WD.tar" \
-F "token=$(W3C_ECHIDNA_TOKEN_JSAPI)" \
-F "decision=$(DECISION_URL)" | tee $(BUILDDIR)/WD-echidna-id.txt
-F "decision=$(DECISION_URL)" \
-F "dry-run=$(ECHIDNA_DRYRUN)" | tee $(BUILDDIR)/WD-echidna-id.txt
python3 ../util/check-echidna-status.py $(BUILDDIR)
@echo
@echo "Published $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
@echo "Uploaded $(W3C_STATUS). Check its status at https://labs.w3.org/echidna/api/status?id=`cat $(BUILDDIR)/WD-echidna-id.txt`"
55 changes: 49 additions & 6 deletions document/js-api/index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ Date: now
"title": "WebAssembly Core Specification",
"publisher": "W3C WebAssembly Community Group",
"status": "Draft"
},
"WASMWEB": {
"href": "https://webassembly.github.io/spec/js-api/",
"title": "WebAssembly Web API Specification",
"publisher": "W3C WebAssembly Community Group",
"status": "Draft"
}
}
</pre>
Expand Down Expand Up @@ -63,10 +69,17 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
text: 𝔽; url: #𝔽
text: ℤ; url: #ℤ
text: SameValue; url: sec-samevalue
text: Array; url: sec-array-exotic-objects
text: BigInt; url: sec-ecmascript-language-types-bigint-type
urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: dfn
text: embedding interface; url: appending/embedding.html
text: scope; url: intro/introduction.html#scope
url: valid/modules.html#valid-module
text: valid
text: WebAssembly module validation
text: valid limits; url: valid/types.html#valid-limits
text: valid memtype; url: valid/types.html#valid-memtype
text: valid tabletype; url: valid/types.html#valid-tabletype
text: module grammar; url: binary/modules.html#binary-module
text: custom section; url: binary/modules.html#custom-section
text: customsec; url: binary/modules.html#binary-customsec
Expand Down Expand Up @@ -122,9 +135,11 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
text: match_valtype; url: appendix/embedding.html#embed-match-valtype
text: error; url: appendix/embedding.html#embed-error
text: store; url: exec/runtime.html#syntax-store
text: limits; url: syntax/types.html#syntax-limits
text: table type; url: syntax/types.html#syntax-tabletype
text: table address; url: exec/runtime.html#syntax-tableaddr
text: function address; url: exec/runtime.html#syntax-funcaddr
text: memory type; url: syntax/types.html#syntax-memtype
text: memory address; url: exec/runtime.html#syntax-memaddr
text: global address; url: exec/runtime.html#syntax-globaladdr
text: tag address; url: exec/runtime.html#syntax-tagaddr
Expand Down Expand Up @@ -226,7 +241,14 @@ emu-const {
}
</style>

This API provides a way to access WebAssembly [[WEBASSEMBLY]] through a bridge to explicitly construct modules from JavaScript [[ECMASCRIPT]].
<h2 id="intro">Introduction</h2>

By design, the [=scope=] of the WebAssembly core specification [[WEBASSEMBLY]] does not include a description of how WebAssembly programs interact with their surrounding execution environment.
Instead it defines an abstract [=embedding interface=] between WebAssembly and its environment, (called the *embedder*).
It is only through this interface that an embedder interacts with the semantics of WebAssembly, and the embedder implements the connection between its host environment and the embedding API.
This document describes the embedding of WebAssembly into JavaScript [[ECMASCRIPT]] environments, including how WebAssembly modules can be constructed and instantiated, how imported and exported functions are called, how data is exchanged, and how errors are handled.
When the JavaScript environment is itself embedded in a Web browser, the Web API spec [[WASMWEB]] describes additional behavior relevant to the Web environment.


<h2 id="sample">Sample API Usage</h2>

Expand Down Expand Up @@ -733,8 +755,8 @@ which can be simultaneously referenced by multiple {{Instance}} objects. Each
The <dfn constructor for="Memory">Memory(|descriptor|)</dfn> constructor, when invoked, performs the following steps:
1. Let |initial| be |descriptor|["initial"].
1. If |descriptor|["maximum"] [=map/exists=], let |maximum| be |descriptor|["maximum"]; otherwise, let |maximum| be empty.
1. If |maximum| is not empty and |maximum| &lt; |initial|, throw a {{RangeError}} exception.
1. Let |memtype| be { min |initial|, max |maximum| }.
1. Let |memtype| be the [=memory type=] { <b>[=limits|min=]</b> |initial|, <b>[=limits|max=]</b> |maximum| }.
1. If |memtype| is not [=valid memtype|valid=], throw a {{RangeError}} exception.
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
1. Let (|store|, |memaddr|) be [=mem_alloc=](|store|, |memtype|). If allocation fails, throw a {{RangeError}} exception.
1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
Expand Down Expand Up @@ -894,15 +916,17 @@ Each {{Table}} object has a \[[Table]] internal slot, which is a [=table address
1. Throw a {{TypeError}} exception.
1. Let |initial| be |descriptor|["initial"].
1. If |descriptor|["maximum"] [=map/exists=], let |maximum| be |descriptor|["maximum"]; otherwise, let |maximum| be empty.
1. If |maximum| is not empty and |maximum| &lt; |initial|, throw a {{RangeError}} exception.
1. Let |type| be the [=table type=] { <b>[=limits|min=]</b> |initial|, <b>[=limits|max=]</b> |maximum| } |elementType|.
1. If |type| is not [=valid tabletype|valid=], throw a {{RangeError}} exception.

Note: Because tables may have up to 2<sup>32</sup> - 1 elements in validation, the checks for [=limits|min=] ≤ 2<sup>32</sup> - 1 and [=limits|max=] ≤ 2<sup>32</sup> - 1 in [=valid limits|limits validation=] cannot fail.
1. If |value| is missing,
1. Let |ref| be [=DefaultValue=](|elementType|).
1. Assert: |ref| is not [=error=].
1. Otherwise,
1. Let |ref| be [=?=] [=ToWebAssemblyValue=](|value|, |elementType|).
1. Let |type| be the [=table type=] {[=table type|min=] |initial|, [=table type|max=] |maximum|} |elementType|.
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
1. Let (|store|, |tableaddr|) be [=table_alloc=](|store|, |type|, |ref|). <!-- TODO(littledan): Report allocation failure https://github.com/WebAssembly/spec/issues/584 -->
1. Let (|store|, |tableaddr|) be [=table_alloc=](|store|, |type|, |ref|). If allocation fails, throw a {{RangeError}} exception.
1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
1. [=initialize a table object|Initialize=] **this** from |tableaddr|.
</div>
Expand Down Expand Up @@ -1736,3 +1760,22 @@ In practice, an implementation may run out of resources for valid modules below
<p><em>This section is non-normative.</em></p>

This document defines a host environment for WebAssembly. It enables a WebAssembly instance to [=import=] JavaScript objects and functions from an [=read the imports|import object=], but otherwise provides no access to the embedding environment. Thus a WebAssembly instance is bound to the same constraints as JavaScript.

<h2 id="change-history">Change History</h2>

<p><em>This section is non-normative.</em></p>

<p>Since the original release 1.0 of the WebAssembly specification, a number of proposals for extensions have been integrated.
The following sections provide an overview of what has changed.</p>

<h3 id="release-20">Release 2.0</h3>

<h4 id="changes-multivalue" class="no-toc heading settled">Multiple Values</h4>
Multiple values can be returned from WebAssembly functions into JavaScript as an [=Array=] object.

<h4 id="changes-bigint" class="no-toc heading settled">BigInt Integration</h4>
WebAssembly [=i64=] values can be passed to and from JavaScript (via imported or exported globals, table get or set operations, function return values or arguments) as [=BigInt=] objects.

<h4 id="changes-reftypes" class="no-toc heading settled">Reference types</h4>
JavaScript values can be passed to and from WebAssembly (via imported or exported globals, table set or get operations, and function arguments or return values) as [=externref=] values.
Multiple tables can be exported and imported to and from JavaScript.
Loading

0 comments on commit 87789ff

Please sign in to comment.