feat(mem-alloc): enhance aligned allocation metadata and documentation

Author: lum1n0us

core/shared/mem-alloc/ems/ems_gc_internal.h

@@ -92,7 +92,7 @@ hmu_verify(void *vheap, hmu_t *hmu);
 
 /* Minimum alignment for allocations */
 #ifndef GC_MIN_ALIGNMENT
-#define GC_MIN_ALIGNMENT  8
+#define GC_MIN_ALIGNMENT 8
 #endif
 
 #define GC_SMALLEST_SIZE \
@@ -101,9 +101,22 @@ hmu_verify(void *vheap, hmu_t *hmu);
     GC_ALIGN_8(HMU_SIZE + OBJ_PREFIX_SIZE + OBJ_SUFFIX_SIZE \
                + (((x) > 8) ? (x) : 8))
 
-/* Magic value for aligned allocation detection */
-#define ALIGNED_ALLOC_MAGIC_MASK   0xFFFF0000
-#define ALIGNED_ALLOC_MAGIC_VALUE  0xA11C0000
+/*
+ * Aligned allocation uses metadata in the header to store the offset
+ *
+ * ### Memory Layout
+ *
+ * Aligned allocations use over-allocation with metadata storage:
+ *
+ * ```
+ * [HMU][PREFIX][...padding...][METADATA][ALIGNED_OBJ][SUFFIX]
+ *                              ^8 bytes  ^returned pointer (aligned)
+ * ```
+ *
+ * Magic value for aligned allocation detection
+ */
+#define ALIGNED_ALLOC_MAGIC_MASK 0xFFFF0000
+#define ALIGNED_ALLOC_MAGIC_VALUE 0xA11C0000
 
 /**
  * hmu bit operation
@@ -125,9 +138,49 @@ hmu_verify(void *vheap, hmu_t *hmu);
     (((v) & (((((uint32)1 << size) - 1) << offset))) >> offset)
 /* clang-format on */
 
+/* clang-format off */
 /**
  * gc object layout definition
+ *
+ * #### Header Bit Layout
+ * 
+ * ```
+ * 31 30 29 28 27                                                    0
+ * ┌──┬──┬──┬──┬───────────────────────────────────────────────────┐
+ * │UT│UT│ P│ *│            Size or Type-Specific Data             │
+ * └──┴──┴──┴──┴───────────────────────────────────────────────────┘
+ * ```
+ *
+ * #### Bit Fields Breakdown
+ *
+ * | Bits      | Field                   | Description                                  |
+ * | --------- | ----------------------- | -------------------------------------------- |
+ * | **31-30** | **UT** (Usage Type)     | 2 bits for chunk type                        |
+ * | **29**    | **P** (Previous In Use) | 1 bit indicating if previous chunk is in use |
+ * | **28**    | **Type-specific**       | Meaning depends on UT field                  |
+ * | **27-0**  | **Type-specific**       | Size or other data depending on UT           |
+ * 
+ * #### Memory Layout in Heap
+ * 
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │  HMU Header (4 bytes)                                       │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │  OBJ_PREFIX (if BH_ENABLE_GC_VERIFY)                        │
+ * │    - file_name pointer                                      │
+ * │    - line_no                                                │
+ * │    - size                                                   │
+ * │    - padding values (for corruption detection)              │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │  User Data (aligned to 8 bytes)                             │
+ * │  ...                                                        │
+ * ├─────────────────────────────────────────────────────────────┤
+ * │  OBJ_SUFFIX (if BH_ENABLE_GC_VERIFY)                        │
+ * │    - padding values (for corruption detection)              │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
  */
+/* clang-format on */
 
 #define HMU_SIZE (sizeof(hmu_t))