Skip to content

wasm: Enable 64bit guests on TCI using wasm64

Kohei Tokunaga qemu-devel 6 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v4 posting 2/233 patches 5 repliesIn review
  2. v5 Latest4 patches 5 repliesIn review
  3. v4 posting 1/24 patches 5 repliesSuperseded
Earlier versions · 3
VersionPostedPatchesRepliesStatus
v335 patches5 repliesSuperseded
v235 patches0 repliesSuperseded
v135 patches10 repliesSuperseded

Changes in v5 from the cover letter

- In emsdk-wasm-cross.docker, removed -sMEMORY64 from the environment variables (e.g. CFLAGS) in the QEMU compilation stage.
- Updated the Dockerfile to build dependencies always with -sMEMORY64=1 for wasm64 target. The final QEMU compilation can be lowered to wasm32 by using configure's --wasm64-32bit-address-limit flag which enables Emscripten's MEMORY64=2.
- Fixed wasm64 tests (build-wasm64-64bit and build-wasm64-32bit) to share the same wasm64 container. The build-wasm64-32bit test passes --wasm64-32bit-address-limit to the configure script so that the output is lowered to wasm32 by Emscripten's -sMEMORY64=2.

Patches in v5 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/4meson: Add wasm64 support to the --cpu flagconfigure meson.build+7 -31 reply
2/4configure: Enable to propagate -sMEMORY64 flag to Emscriptenconfigure+11 -10 replies
3/4dockerfiles: Add support for wasm64 to the wasm DockerfileMAINTAINERS tests/docker/dockerfiles/emsdk-wasm-cross.docker+20 -80 replies
4/4.gitlab-ci.d: Add build tests for wasm64.gitlab-ci.d/buildtest.yml .gitlab-ci.d/container-cross.yml .gitlab-ci.d/container-template.yml +1 more+36 -61 reply

Reviews trailers per patch

All 4 patches have a Reviewed-by or Acked-by.

PatchPierrick BouvierPhilippe Mathieu-Daudé
1/4R-b R-b
2/4R-b R-b
3/4R-b
4/4R-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v5 thread

Cover letter [PATCH v5 0/4] wasm: Enable 64bit guests on TCI using wasm64

V5:

- In emsdk-wasm-cross.docker, removed -sMEMORY64 from the environment variables (e.g. CFLAGS) in the QEMU compilation stage.
- Updated the Dockerfile to build dependencies always with -sMEMORY64=1 for wasm64 target. The final QEMU compilation can be lowered to wasm32 by using configure's --wasm64-32bit-address-limit flag which enables Emscripten's MEMORY64=2.
- Fixed wasm64 tests (build-wasm64-64bit and build-wasm64-32bit) to share the same wasm64 container. The build-wasm64-32bit test passes --wasm64-32bit-address-limit to the configure script so that the output is lowered to wasm32 by Emscripten's -sMEMORY64=2.

V4:

- Rebased on the recent tree.

V3:

- Renamed the build tests on GitLab CI("build-wasm32" -> "build-wasm32-32bit", "build-wasm-wasm64" -> "build-wasm64-64bit", "build-wasm-wasm64l" -> "build-wasm64-32bit"). The same change has also been applied to container-cross.yml.

V2:

- Added a link to the Emscripten documentation about -sMEMORY64 in the configure script.
- Changed --wasm64-memory64 flag to --wasm64-32bit-address-limit to avoid exposing the -sMEMORY64 value directly to the users.
- Fixed GitLab CI to use --wasm64-32bit-address-limit instead of --wasm64-memory64.

V1:

This patch series enables the TCI of the Wasm build to run 64bit guests. Unlike the previous series[1], this patch series is implemented by adding support for WebAssembly's "wasm64" target which enables 64bit pointers.

In the previous discussion[2], the main challenge of using wasm64 was its limited adoption, particularly the lack of support in our dependency (libffi) and some engines such as Safari.

For libffi, I've completed the addition of wasm64 support upstream[3] so it can be used.

To support wasm32 engines, this patch uses Emscripten's compatibility feature, -sMEMORY64=2 flag[4]. This flag still enables 64bit pointers in the C code while Emscripten lowers the output binary to wasm32 and limits the maximum memory size to 4GB. As a result, QEMU can run on wasm32 engiens while still supporting 64bit guests.

# Overview of the build process

To compile QEMU with Emscripten, the following dependencies are required. The emsdk-wasm-cross.docker environment includes all necessary components and can be used as the build environment:

- Emscripten SDK (emsdk) v4.0.10
- Libraries cross-compiled with Emscripten (please see also emsdk-wasm-cross.docker for build steps)
- GLib v2.84.0
- zlib v1.3.1
- libffi v3.5.2
- Pixman v0.44.2

The configure script supports --cpu=wasm64 flag to compile QEMU with 64bit pointer support.

emconfigure ./configure --cpu=wasm64 \
                        --static --disable-tools \
                        --target-list=x86_64-softmmu \
                        --enable-tcg-interpreter

emmake make -j$(nproc)

If the output needs to run on wasm32 engines, use --wasm64-32bit-address-limit flag. This flag enables Emscripten's -sMEMORY64=2 flag[4]. (Note: --wasm64-memory64=2 flag in the V1 patch has been renamed to --wasm64-32bit-address-limit in V2)

emconfigure ./configure --cpu=wasm64 --wasm64-32bit-address-limit \
                        --static --disable-tools \
                        --target-list=x86_64-softmmu \
                        --enable-tcg-interpreter

emmake make -j$(nproc)

Either of the above commands generates the following files:

- qemu-system-x86_64.js
- qemu-system-x86_64.wasm

Guest images can be packaged using Emscripten's file_packager.py tool. For example, if the images are stored in a directory named "pack", the following command packages them, allowing QEMU to access them through Emscripten's virtual filesystem:

/path/to/file_packager.py qemu-system-x86_64.data --preload pack > load.js

This process generates the following files:

- qemu-system-x86_64.data
- load.js

Emscripten allows passing arguments to the QEMU command via the Module object in JavaScript:

Module['arguments'] = [

    '-nographic', '-m', '512M',
    '-L', 'pack/',
    '-drive', 'if=virtio,format=raw,file=pack/rootfs.bin',
    '-kernel', 'pack/bzImage',
    '-append', 'earlyprintk=ttyS0 console=ttyS0 root=/dev/vda loglevel=7',

];

The sample repository[5] (tcidev64 branch) provides a complete setup, including an HTML file that implements a terminal UI.

[1] https://lists.nongnu.org/archive/html/qemu-devel/2025-05/msg05376.html
[2] https://lists.nongnu.org/archive/html/qemu-devel/2025-04/msg01795.html
[3] https://github.com/libffi/libffi/pull/927
[4] https://emscripten.org/docs/tools_reference/settings_reference.html#memory64
[5] https://github.com/ktock/qemu-wasm-sample/tree/tcidev64

Kohei Tokunaga (4):
meson: Add wasm64 support to the --cpu flag
configure: Enable to propagate -sMEMORY64 flag to Emscripten
dockerfiles: Add support for wasm64 to the wasm Dockerfile .gitlab-ci.d: Add build tests for wasm64

 .gitlab-ci.d/buildtest.yml                    | 24 ++++++++++++++---
 .gitlab-ci.d/container-cross.yml              | 11 +++++++-
 .gitlab-ci.d/container-template.yml           |  4 ++-
 .gitlab-ci.d/containers.yml                   |  3 ++-
 MAINTAINERS                                   |  2 +-
 configure                                     | 16 +++++++++++-
 meson.build                                   |  4 +--
 ...2-cross.docker => emsdk-wasm-cross.docker} | 26 ++++++++++++++-----
 8 files changed, 73 insertions(+), 17 deletions(-)
 rename tests/docker/dockerfiles/{emsdk-wasm32-cross.docker => emsdk-wasm-cross.docker} (89%)
Signature · 1 line
2.43.0