refactor(mem-alloc): improve aligned allocation design and documentation

lum1n0us · claude · lum1n0us · commit a02ad8bcab61 · 2026-03-26T11:44:35.000+08:00
This commit addresses several design improvements for aligned allocation:

1. **Size=0 behavior consistency**:
   - wasm_runtime_aligned_alloc(0, N) now allocates N bytes (smallest valid size)
   - Matches wasm_runtime_malloc(0) behavior which allocates 1 byte
   - Ensures size is always a multiple of alignment

2. **Helper function for alignment detection**:
   - Add gc_is_aligned_allocation() inline helper in ems_gc_internal.h
   - Encapsulates magic marker check logic (DRY principle)
   - Used in obj_to_hmu() and gc_realloc_vo_internal()
   - Single source of truth for alignment detection

3. **Global API visibility macro**:
   - Add WASM_RUNTIME_API_INTERN to bh_platform.h
   - Centralizes internal API visibility control
   - MEM_ALLOC_API_INTER now uses WASM_RUNTIME_API_INTERN
   - Consistent with WASM_RUNTIME_API_EXTERN pattern

4. **Comprehensive documentation**:
   - Replace brief comment with 90+ line documentation block
   - Explain POSIX aligned_alloc() specification (C11 §7.22.3.1)
   - Describe WAMR implementation strategy in detail:
     * Validation, over-allocation, alignment adjustment
     * Magic marker storage (0xA11C0000 | offset)
     * Realloc prevention mechanism
   - Include memory layout diagram with ASCII art
   - Document constraints, limitations, and usage examples
   - Helps future maintainers understand design decisions

Files changed:
- core/iwasm/common/wasm_memory.c: Fix size=0 behavior
- core/shared/utils/bh_platform.h: Add WASM_RUNTIME_API_INTERN
- core/shared/mem-alloc/ems/ems_gc_internal.h: Add helper + docs
- core/shared/mem-alloc/ems/ems_alloc.c: Use helper function
- tests/unit/mem-alloc/mem_alloc_test.c: Update test expectations

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/core/iwasm/common/wasm_memory.c b/core/iwasm/common/wasm_memory.c
@@ -1073,16 +1073,20 @@ wasm_runtime_malloc(unsigned int size)
 void *
 wasm_runtime_aligned_alloc(unsigned int size, unsigned int alignment)
 {
-    if (size == 0) {
-        LOG_WARNING("warning: wasm_runtime_aligned_alloc with size zero\n");
-        return NULL;
-    }
-
     if (alignment == 0) {
         LOG_WARNING("warning: wasm_runtime_aligned_alloc with zero alignment\n");
         return NULL;
     }
 
+    if (size == 0) {
+        LOG_WARNING("warning: wasm_runtime_aligned_alloc with size zero\n");
+        /* Allocate at least alignment bytes (smallest multiple of alignment) */
+        size = alignment;
+#if BH_ENABLE_GC_VERIFY != 0
+        exit(-1);
+#endif
+    }
+
 #if WASM_ENABLE_FUZZ_TEST != 0
     if (size >= WASM_MEM_ALLOC_MAX_SIZE) {
         LOG_WARNING("warning: wasm_runtime_aligned_alloc with too large size\n");
diff --git a/core/shared/mem-alloc/ems/ems_alloc.c b/core/shared/mem-alloc/ems/ems_alloc.c
@@ -556,10 +556,8 @@ alloc_hmu_ex(gc_heap_t *heap, gc_size_t size)
 MEM_ALLOC_API_INTER hmu_t *
 obj_to_hmu(gc_object_t obj)
 {
-    uint32_t *magic_ptr = (uint32_t *)((char *)obj - 4);
-
     /* Check for aligned allocation magic signature */
-    if ((*magic_ptr & ALIGNED_ALLOC_MAGIC_MASK) == ALIGNED_ALLOC_MAGIC_VALUE) {
+    if (gc_is_aligned_allocation(obj)) {
         /* This is an aligned allocation, read offset */
         uint32_t *offset_ptr = (uint32_t *)((char *)obj - 8);
         return (hmu_t *)((char *)obj - *offset_ptr);
@@ -779,13 +777,10 @@ gc_realloc_vo_internal(void *vheap, void *ptr, gc_size_t size, const char *file,
 #endif
 
     /* Check if this is an aligned allocation - not supported */
-    if (obj_old) {
-        uint32_t *magic_ptr = (uint32_t *)((char *)obj_old - 4);
-        if ((*magic_ptr & ALIGNED_ALLOC_MAGIC_MASK) == ALIGNED_ALLOC_MAGIC_VALUE) {
-            LOG_ERROR("[GC_ERROR]gc_realloc_vo does not support aligned "
-                      "allocations\n");
-            return NULL;
-        }
+    if (gc_is_aligned_allocation(obj_old)) {
+        LOG_ERROR("[GC_ERROR]gc_realloc_vo does not support aligned "
+                  "allocations\n");
+        return NULL;
     }
 
     if (obj_old) {
diff --git a/core/shared/mem-alloc/ems/ems_gc_internal.h b/core/shared/mem-alloc/ems/ems_gc_internal.h
@@ -15,11 +15,7 @@ extern "C" {
 
 /* Test visibility macro for internal functions */
 #ifndef MEM_ALLOC_API_INTER
-#ifdef WAMR_BUILD_TEST
-#define MEM_ALLOC_API_INTER
-#else
-#define MEM_ALLOC_API_INTER static
-#endif
+#define MEM_ALLOC_API_INTER WASM_RUNTIME_API_INTERN
 #endif
 
 /* HMU (heap memory unit) basic block type */
@@ -102,22 +98,119 @@ hmu_verify(void *vheap, hmu_t *hmu);
                + (((x) > 8) ? (x) : 8))
 
 /*
- * Aligned allocation uses metadata in the header to store the offset
+ * ============================================================================
+ * Aligned Memory Allocation
+ * ============================================================================
  *
- * ### Memory Layout
+ * This module implements aligned memory allocation similar to C11 aligned_alloc()
+ * and POSIX posix_memalign() for WAMR's garbage collector.
  *
- * Aligned allocations use over-allocation with metadata storage:
+ * POSIX aligned_alloc() Specification:
+ * ------------------------------------
+ * From C11 §7.22.3.1 and POSIX.1-2017:
+ *   void *aligned_alloc(size_t alignment, size_t size);
  *
- * ```
- * [HMU][PREFIX][...padding...][METADATA][ALIGNED_OBJ][SUFFIX]
- *                              ^8 bytes  ^returned pointer (aligned)
- * ```
+ * Requirements:
+ * - alignment: Must be a valid alignment supported by the implementation,
+ *              typically a power of 2
+ * - size: Must be an integral multiple of alignment
+ * - Returns: Pointer aligned to the specified alignment boundary, or NULL
+ * - Memory must be freed with free() (not realloc'd)
+ * - Behavior: If size is 0, may return NULL or unique pointer (impl-defined)
+ *
+ * IMPORTANT: POSIX does not require realloc() to preserve alignment.
+ * Calling realloc() on aligned_alloc() memory has undefined behavior.
+ *
+ * WAMR Implementation Strategy:
+ * -----------------------------
+ * We implement alignment through over-allocation with metadata tracking:
+ *
+ * 1. **Validation Phase**:
+ *    - Check alignment is power-of-2, >= 8 bytes, <= system page size
+ *    - Check size is multiple of alignment
+ *    - Return NULL if validation fails
+ *
+ * 2. **Over-Allocation**:
+ *    - Allocate (size + alignment + metadata_overhead) bytes
+ *    - Extra space allows us to find an aligned boundary within the block
+ *    - Calculate log2(alignment) for efficient offset storage
+ *
+ * 3. **Alignment Adjustment**:
+ *    - Find next aligned address within allocated block
+ *    - Calculate offset from original allocation to aligned address
+ *    - Store offset in metadata for later free() operation
+ *
+ * 4. **Magic Marker Storage**:
+ *    - Store magic marker (0xA11C0000 | offset) in 4 bytes before user pointer
+ *    - Upper 16 bits: 0xA11C identifies aligned allocation
+ *    - Lower 16 bits: offset from HMU to aligned pointer (max 65535 bytes)
+ *    - This marker prevents unsafe realloc() operations
+ *
+ * 5. **Realloc Prevention**:
+ *    - gc_realloc_vo_internal() checks for magic marker
+ *    - Returns NULL if realloc attempted on aligned allocation
+ *    - User must manually allocate new memory and copy data
+ *
+ * Memory Layout Diagram:
+ * ----------------------
+ *
+ *  Low Address                                               High Address
+ *  ┌─────────────┬──────────┬────────────────┬──────────────┬─────────────┐
+ *  │ HMU Header  │ Padding  │ Magic + Offset │ Aligned Data │   Padding   │
+ *  │   (meta)    │ (0-align)│    (4 bytes)   │   (size)     │  (overhead) │
+ *  └─────────────┴──────────┴────────────────┴──────────────┴─────────────┘
+ *                             ▲                ▲
+ *                             │                │
+ *                             magic_ptr        user_ptr (returned, aligned)
  *
- * Magic value for aligned allocation detection
+ * Constraints and Limitations:
+ * ----------------------------
+ * - Minimum alignment: 8 bytes (GC_MIN_ALIGNMENT)
+ * - Maximum alignment: System page size (os_getpagesize(), typically 4KB)
+ * - Maximum offset: 65535 bytes (16-bit storage limit)
+ * - Realloc support: None - returns NULL (prevents alignment loss)
+ * - Free support: Full - use mem_allocator_free() / wasm_runtime_free()
+ * - Thread safety: Protected by LOCK_HEAP/UNLOCK_HEAP
+ *
+ * Usage Example:
+ * --------------
+ * // Allocate 256 bytes aligned to 64-byte boundary (e.g., for SIMD)
+ * void *ptr = wasm_runtime_aligned_alloc(256, 64);
+ * assert((uintptr_t)ptr % 64 == 0);  // Guaranteed aligned
+ *
+ * // Use the memory...
+ *
+ * // Free normally (alignment metadata handled automatically)
+ * wasm_runtime_free(ptr);
+ *
+ * // INVALID: Cannot realloc aligned memory
+ * void *new_ptr = wasm_runtime_realloc(ptr, 512);  // Returns NULL!
  */
-#define ALIGNED_ALLOC_MAGIC_MASK 0xFFFF0000
+
+/* Aligned allocation magic markers */
+#define ALIGNED_ALLOC_MAGIC_MASK  0xFFFF0000
 #define ALIGNED_ALLOC_MAGIC_VALUE 0xA11C0000
 
+/**
+ * Check if a gc_object was allocated with alignment requirements.
+ *
+ * Aligned allocations store a magic marker (0xA11C0000) in the 4 bytes
+ * immediately before the object pointer. This marker is used to identify
+ * aligned allocations to prevent unsafe realloc operations.
+ *
+ * @param obj the gc_object to check (user-visible pointer)
+ * @return true if obj is an aligned allocation, false otherwise
+ */
+static inline bool
+gc_is_aligned_allocation(gc_object_t obj)
+{
+    if (!obj)
+        return false;
+
+    uint32_t *magic_ptr = (uint32_t *)((char *)obj - 4);
+    return ((*magic_ptr & ALIGNED_ALLOC_MAGIC_MASK) == ALIGNED_ALLOC_MAGIC_VALUE);
+}
+
 /**
  * hmu bit operation
  */
diff --git a/core/shared/utils/bh_platform.h b/core/shared/utils/bh_platform.h
@@ -18,6 +18,23 @@
 #include "bh_vector.h"
 #include "runtime_timer.h"
 
+/**
+ * API visibility macros for WAMR internal functions
+ *
+ * WASM_RUNTIME_API_EXTERN - Public exported APIs (defined in wasm_export.h)
+ * WASM_RUNTIME_API_INTERN - Internal APIs visible across WAMR components
+ *
+ * In test builds (WAMR_BUILD_TEST=1), internal APIs are exposed for unit testing.
+ * In production builds, internal APIs are static (file-scoped) for encapsulation.
+ */
+#ifndef WASM_RUNTIME_API_INTERN
+#ifdef WAMR_BUILD_TEST
+#define WASM_RUNTIME_API_INTERN
+#else
+#define WASM_RUNTIME_API_INTERN static
+#endif
+#endif
+
 /**
  * WA_MALLOC/WA_FREE need to be redefined for both
  * runtime native and WASM app respectively.
diff --git a/tests/unit/mem-alloc/mem_alloc_test.c b/tests/unit/mem-alloc/mem_alloc_test.c
@@ -406,10 +406,12 @@ test_wasm_runtime_aligned_alloc_zero_size(void **state)
 
     assert_true(wasm_runtime_full_init(&init_args));
 
-    /* Zero size should return NULL */
+    /* Zero size should allocate alignment bytes (like malloc(0) behavior) */
     ptr = wasm_runtime_aligned_alloc(0, 64);
-    assert_null(ptr);
+    assert_non_null(ptr);
+    assert_true(is_aligned(ptr, 64));
 
+    wasm_runtime_free(ptr);
     wasm_runtime_destroy();
     free(init_args.mem_alloc_option.pool.heap_buf);
 }
