From ff7095d501689397661093f2717efa937f60e40d Mon Sep 17 00:00:00 2001 From: "liang.he@intel.com" Date: Fri, 30 Jan 2026 11:01:31 +0800 Subject: [PATCH] Update the GC tiered level from B to C. Several known limitations have been exposed, and a few might impact the estimation when trying to integrate that feature into a product. --- doc/build_wamr.md | 5 +++ doc/stability_wasm_proposals.md | 25 +++++++------- doc/tiered_support.md | 60 ++++++++++++++++----------------- 3 files changed, 48 insertions(+), 42 deletions(-) diff --git a/doc/build_wamr.md b/doc/build_wamr.md index ca27d87ad1..8892769eb0 100644 --- a/doc/build_wamr.md +++ b/doc/build_wamr.md @@ -338,6 +338,11 @@ SIMDE (SIMD Everywhere) implements SIMD operations in fast interpreter mode. - **WAMR_BUILD_STRINGREF**=1/0, default to off. When enabled, need to set WAMR_STRINGREF_IMPL_SOURCE as well > [!WARNING] +> Current implentation of Garbage Collection(GC) is not fully compliant with the Wasm GC proposal and Wasm 3.0 specification. There are still few known limitations: +> +> - `exn` and `noexn` types are not supported. +> - nested structs and arrays are not fully supported. +> > Garbage collection is not supported in fast-jit mode and multi-tier-jit mode. ### **Set the Garbage Collection heap size** diff --git a/doc/stability_wasm_proposals.md b/doc/stability_wasm_proposals.md index 8ad0571192..12f9fee663 100644 --- a/doc/stability_wasm_proposals.md +++ b/doc/stability_wasm_proposals.md @@ -12,17 +12,16 @@ Users can turn those features on or off by using compilation options. If a relev ## On-by-default Wasm Proposals -| Proposal | >= Phase 4 | Compilation Option | -| ------------------------------------- | ---------- |----------------------------| -| Bulk Memory Operations | Yes | `WAMR_BUILD_BULK_MEMORY` | -| Fixed-width SIMD[^1] | Yes | `WAMR_BUILD_SIMD` | -| Import/Export of Mutable Globals[^2] | Yes | N/A | -| Multi-value | Yes | N/A | -| Non-trapping float-to-int Conversions | Yes | N/A | -| Reference Types | Yes | `WAMR_BUILD_REF_TYPES` | -| Sign-extension Operators | Yes | N/A | -| WebAssembly C and C++ API | No | N/A | -| Branch Hinting | Yes | `WASM_ENABLE_BRANCH_HINTS` | +| Proposal | >= Phase 4 | Compilation Option | +| ------------------------------------- | ---------- | ------------------------ | +| Bulk Memory Operations | Yes | `WAMR_BUILD_BULK_MEMORY` | +| Fixed-width SIMD[^1] | Yes | `WAMR_BUILD_SIMD` | +| Import/Export of Mutable Globals[^2] | Yes | N/A | +| Multi-value | Yes | N/A | +| Non-trapping float-to-int Conversions | Yes | N/A | +| Reference Types | Yes | `WAMR_BUILD_REF_TYPES` | +| Sign-extension Operators | Yes | N/A | +| WebAssembly C and C++ API | No | N/A | [^1]: llvm-jit and aot only. @@ -31,7 +30,8 @@ Users can turn those features on or off by using compilation options. If a relev ## Off-by-default Wasm Proposals | Proposal | >= Phase 4 | Compilation Option | -| ----------------------------- | ---------- | ---------------------------------| +| ----------------------------- | ---------- | -------------------------------- | +| Branch Hinting | Yes | `WASM_ENABLE_BRANCH_HINTS` | | Extended Constant Expressions | Yes | `WAMR_BUILD_EXTENDED_CONST_EXPR` | | Garbage Collection | Yes | `WAMR_BUILD_GC` | | Legacy Exception Handling[^3] | No | `WAMR_BUILD_EXCE_HANDLING` | @@ -49,6 +49,7 @@ Users can turn those features on or off by using compilation options. If a relev this proposal is discouraged. [^4]: interpreter only + [^5]: `WAMR_BUILD_LIB_PTHREAD` can also be used to enable ## Unimplemented Wasm Proposals diff --git a/doc/tiered_support.md b/doc/tiered_support.md index 21adb31156..364d93e5e1 100644 --- a/doc/tiered_support.md +++ b/doc/tiered_support.md @@ -93,7 +93,6 @@ This tier indicates experimental features with foundational support levels. Thes | Nuttx Compatibility | WAMR_BUILD_PALTFORM=nuttx | Portability | | SGX Compatibility | WAMR_BUILD_PALTFORM=linux-sgx | Portability | | Zephyr Compatibility | WAMR_BUILD_PALTFORM=zephyr | Portability | -| GC (Garbage Collection) | [WAMR_BUILD_GC](./build_wamr.md#garbage-collection) | Wasm Proposal | | Stringref | [WAMR_BUILD_STRINGREF](./build_wamr.md#garbage-collection) | Wasm Proposal | | Tail Calls | [WAMR_BUILD_TAIL_CALL](./build_wamr.md#tail-call-feature) | Wasm Proposal | | LLVM JIT | [WAMR_BUILD_JIT](./build_wamr.md#configure-llvm-jit) | Running mode | @@ -108,7 +107,6 @@ This tier indicates experimental features with foundational support levels. Thes | Copy Call Stack | [WAMR_BUILD_COPY_CALL_STACK](./build_wamr.md#copy-call-stack) | Runtime Extensions | | Debug Interpreter | [WAMR_BUILD_DEBUG_INTERP](./build_wamr.md#configure-debug) | Runtime Extensions | | Dump call stack | [WAMR_BUILD_DUMP_CALL_STACK](./build_wamr.md#dump-call-stack-feature) | Runtime Extensions | -| Garbage Collection Heap Verify | [WAMR_BUILD_GC_HEAP_VERIFY](./build_wamr.md#garbage-collection) | Runtime Extensions | | Native General Invocation | [WAMR_BUILD_INVOKE_NATIVE_GENERAL](./build_wamr.md#invoke-general-ffi) | Runtime Extensions | | Lazy JIT Compilation | [WAMR_BUILD_LAZY_JIT](./build_wamr.md#configure-llvm-jit) | Runtime Extensions | | Pthread | [WAMR_BUILD_LIB_PTHREAD](./build_wamr.md#lib-pthread) | Runtime Extensions | @@ -153,31 +151,33 @@ This tier indicates experimental features with foundational support levels. Thes ## Features -| Description | Compilation Flags | Labels | -| ------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------ | -| AliOS compatibility | WAMR_BUILD_PLATFORM=alios-things | Portability | -| Android Compatibility | WAMR_BUILD_PLATFORM=android | Portability | -| Cosmo Compatibility | WAMR_BUILD_PLATFORM=cosmopolitan | Portability | -| FreeBSD Compatibility | WAMR_BUILD_PLATFORM=freebsd | Portability | -| iOS Compatibility | WAMR_BUILD_PLATFORM=darwin | Portability | -| RIOT OS Compatibility | WAMR_BUILD_PLATFORM=riot | Portability | -| RT-Thread Compatibility | WAMR_BUILD_PLATFORM=rt-thread | Portability | -| VxWorks Compatibility | WAMR_BUILD_PLATFORM=vxworks | Portability | -| Windows Compatibility | WAMR_BUILD_PLATFORM=windows | Portability | -| Legacy Exception Handling | [WAMR_BUILD_EXCE_HANDLING](./build_wamr.md#exception-handling) | Wasm Proposal | -| Multi-memory | [WAMR_BUILD_MULTI_MEMORY](./build_wamr.md#multi-memory) | Wasm Proposal | -| Fast JIT | [WAMR_BUILD_FAST_JIT](./build_wamr.md#configure-fast-jit) | Running mode | -| Multi-tier JIT | [Combination of flags](./build_wamr.md#configure-multi-tier-jit) | Running mode | -| AoT Validator | [WAMR_BUILD_AOT_VALIDATOR](./build_wamr.md#aot-validator) | Runtime Extensions | -| Debug AOT | [WAMR_BUILD_DEBUG_AOT](./build_wamr.md#configure-debug) | Runtime Extensions | -| Dynamic AoT debugging | [WAMR_BUILD_DYNAMIC_AOT_DEBUG](./build_wamr.md#configure-debug) | Runtime Extensions | -| Fast JIT Dump | [WAMR_BUILD_FAST_JIT_DUMP](./build_wamr.md#configure-fast-jit) | Runtime Extensions | -| Instruction Metering | [WAMR_BUILD_INSTRUCTION_METERING](./build_wamr.md#instruction-metering) | Runtime Extensions | -| Libc EMCC Compatibility | [WAMR_BUILD_LIBC_EMCC](./build_wamr.md#libc-emcc) | Runtime Extensions | -| Libc UVWASI Compatibility | [WAMR_BUILD_LIBC_UVWASI](./build_wamr.md#libc-uvwasi) | Runtime Extensions | -| RATS Library | [WAMR_BUILD_LIB_RATS](./build_wamr.md#librats) | Runtime Extensions | -| Mini Loader | [WAMR_BUILD_MINI_LOADER](./build_wamr.md#wasm-mini-loader) | Runtime Extensions | -| SGX IPFS Support | [WAMR_BUILD_SGX_IPFS](./build_wamr.md#intel-protected-file-system) | Runtime Extensions | -| Static PGO | [WAMR_BUILD_STATIC_PGO](./build_wamr.md#running-pgoprofile-guided-optimization-instrumented-aot-file) | Runtime Extensions | -| WASM cache | [WAMR_BUILD_WASM_CACHE](./build_wamr.md#wasm-cache) | Runtime Extensions | -| Test garbage collection | [WAMR_TEST_GC](./build_wamr.md#test-garbage-collection) | Runtime Extensions | +| Description | Compilation Flags | Labels | +| ------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------ | +| AliOS compatibility | WAMR_BUILD_PLATFORM=alios-things | Portability | +| Android Compatibility | WAMR_BUILD_PLATFORM=android | Portability | +| Cosmo Compatibility | WAMR_BUILD_PLATFORM=cosmopolitan | Portability | +| FreeBSD Compatibility | WAMR_BUILD_PLATFORM=freebsd | Portability | +| iOS Compatibility | WAMR_BUILD_PLATFORM=darwin | Portability | +| RIOT OS Compatibility | WAMR_BUILD_PLATFORM=riot | Portability | +| RT-Thread Compatibility | WAMR_BUILD_PLATFORM=rt-thread | Portability | +| VxWorks Compatibility | WAMR_BUILD_PLATFORM=vxworks | Portability | +| Windows Compatibility | WAMR_BUILD_PLATFORM=windows | Portability | +| GC (Garbage Collection) | [WAMR_BUILD_GC](./build_wamr.md#garbage-collection) | Wasm Proposal | +| Legacy Exception Handling | [WAMR_BUILD_EXCE_HANDLING](./build_wamr.md#exception-handling) | Wasm Proposal | +| Multi-memory | [WAMR_BUILD_MULTI_MEMORY](./build_wamr.md#multi-memory) | Wasm Proposal | +| Fast JIT | [WAMR_BUILD_FAST_JIT](./build_wamr.md#configure-fast-jit) | Running mode | +| Multi-tier JIT | [Combination of flags](./build_wamr.md#configure-multi-tier-jit) | Running mode | +| AoT Validator | [WAMR_BUILD_AOT_VALIDATOR](./build_wamr.md#aot-validator) | Runtime Extensions | +| Debug AOT | [WAMR_BUILD_DEBUG_AOT](./build_wamr.md#configure-debug) | Runtime Extensions | +| Dynamic AoT debugging | [WAMR_BUILD_DYNAMIC_AOT_DEBUG](./build_wamr.md#configure-debug) | Runtime Extensions | +| Fast JIT Dump | [WAMR_BUILD_FAST_JIT_DUMP](./build_wamr.md#configure-fast-jit) | Runtime Extensions | +| Garbage Collection Heap Verify | [WAMR_BUILD_GC_HEAP_VERIFY](./build_wamr.md#garbage-collection) | Runtime Extensions | +| Instruction Metering | [WAMR_BUILD_INSTRUCTION_METERING](./build_wamr.md#instruction-metering) | Runtime Extensions | +| Libc EMCC Compatibility | [WAMR_BUILD_LIBC_EMCC](./build_wamr.md#libc-emcc) | Runtime Extensions | +| Libc UVWASI Compatibility | [WAMR_BUILD_LIBC_UVWASI](./build_wamr.md#libc-uvwasi) | Runtime Extensions | +| RATS Library | [WAMR_BUILD_LIB_RATS](./build_wamr.md#librats) | Runtime Extensions | +| Mini Loader | [WAMR_BUILD_MINI_LOADER](./build_wamr.md#wasm-mini-loader) | Runtime Extensions | +| SGX IPFS Support | [WAMR_BUILD_SGX_IPFS](./build_wamr.md#intel-protected-file-system) | Runtime Extensions | +| Static PGO | [WAMR_BUILD_STATIC_PGO](./build_wamr.md#running-pgoprofile-guided-optimization-instrumented-aot-file) | Runtime Extensions | +| WASM cache | [WAMR_BUILD_WASM_CACHE](./build_wamr.md#wasm-cache) | Runtime Extensions | +| Test garbage collection | [WAMR_TEST_GC](./build_wamr.md#test-garbage-collection) | Runtime Extensions |