From e352f0ab101116c46a5a615d5139b70e8e9a3d47 Mon Sep 17 00:00:00 2001
From: "liang.he" <liang.he@intel.com>
Date: Fri, 1 Nov 2024 10:16:24 +0800
Subject: [PATCH] Refactor AOT loader to support compatible versions (#3891)

This commit refactors the AOT loader in `aot_loader.c` to support compatible
versions of the AOT_CURRENT_VERSION constant. Previously, the loader only
accepted the exact AOT_CURRENT_VERSION value, but now it also accepts
version 3. This change ensures that the runtime can load modules AoT-compiled
with different versions of wamrc as long as they have compatible
AOT_CURRENT_VERSION values.

Related to #3880.
---
 core/iwasm/aot/aot_loader.c | 12 +++++++++++-
 doc/build_wasm_app.md       | 14 +++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/core/iwasm/aot/aot_loader.c b/core/iwasm/aot/aot_loader.c
index c53503be2..dd26bbee5 100644
--- a/core/iwasm/aot/aot_loader.c
+++ b/core/iwasm/aot/aot_loader.c
@@ -4236,6 +4236,16 @@ fail:
     return false;
 }
 
+static bool
+aot_compatible_version(uint32 version)
+{
+    /*
+     * refer to "AoT-compiled module compatibility among WAMR versions" in
+     * ./doc/biuld_wasm_app.md
+     */
+    return version == 4 || version == 3;
+}
+
 static bool
 load(const uint8 *buf, uint32 size, AOTModule *module,
      bool wasm_binary_freeable, bool no_resolve, char *error_buf,
@@ -4254,7 +4264,7 @@ load(const uint8 *buf, uint32 size, AOTModule *module,
     }
 
     read_uint32(p, p_end, version);
-    if (version != AOT_CURRENT_VERSION) {
+    if (!aot_compatible_version(version)) {
         set_error_buf(error_buf, error_buf_size, "unknown binary version");
         return false;
     }
diff --git a/doc/build_wasm_app.md b/doc/build_wasm_app.md
index 7747d9ac3..9536d1a8d 100644
--- a/doc/build_wasm_app.md
+++ b/doc/build_wasm_app.md
@@ -377,15 +377,23 @@ Examples: wamrc -o test.aot test.wasm
 When making major ABI changes for AoT-compiled modules, we bump
 `AOT_CURRENT_VERSION` constant in `core/config.h` header.
 The runtime rejects to load a module AoT-compiled with wamrc with
-a different `AOT_CURRENT_VERSION`.
+a non-compatible`AOT_CURRENT_VERSION`.
 
 We try our best to maintain our runtime ABI for AoT-compiled modules
-compatible among WAMR versions with the same `AOT_CURRENT_VERSION`
+compatible among WAMR versions with compatible `AOT_CURRENT_VERSION`
 so that combinations of older wamrc and newer runtime usually work.
 However, there might be minor incompatibilities time to time.
-For productions, we recommend to use the exactly same version of
+For productions, we recommend to use compatible versions of
 wamrc and the runtime.
 
+| WAMR version | AOT_CURRENT_VERSION | Compatible AOT version |
+| ------------ | ------------------- | ---------------------- |
+| 1.x          | 3                   | 3                      |
+| 2.0.0        | 3                   | 3                      |
+| 2.1.x        | 3                   | 3                      |
+| 2.2.0        | 3                   | 3                      |
+| next         | 4                   | 3,4                    |
+
 ## AoT compilation with 3rd-party toolchains
 
 `wamrc` uses LLVM to compile wasm bytecode to AoT file, this works for most of the architectures, but there may be circumstances where you want to use 3rd-party toolchains to take over some steps of the compilation pipeline, e.g.