lib: heap: compute Z_HEAP_MIN_SIZE from actual struct layouts

Z_HEAP_MIN_SIZE and Z_HEAP_MIN_SIZE_FOR were defined in kernel.h as
hardcoded magic numbers gated by a growing tower of #ifdefs — one
per Kconfig option that happened to affect the heap struct layout.
Every internal change required manually recomputing the constants,
duplicating layout knowledge across files, and praying nobody forgot
to update the #ifdef matrix.  This is fragile and unscalable: adding
a single new heap feature (e.g. a chunk canary trailer) would add yet
another dimension to the combinatorial explosion.

Replace this with build-time computation from the actual C structures.
A new lib/heap/heap_constants.c is compiled as part of the offsets
library and uses GEN_ABSOLUTE_SYM to emit the correct values into the
generated offsets.h.  Z_HEAP_MIN_SIZE is derived through an iterative
fixed-point expansion (3 rounds, always convergent) that mirrors the
runtime logic in sys_heap_init().  Z_HEAP_MIN_SIZE_FOR overhead and
bucket sizes are also generated, keeping all internal heap layout
knowledge in one place.

Big vs small heap determination uses CONFIG_SYS_HEAP_SMALL_ONLY,
CONFIG_SYS_HEAP_BIG_ONLY, and sizeof(void *), mirroring the
big_heap_chunks() logic in heap.h.

kernel.h picks up the generated values via
__has_include(<zephyr/offsets.h>) so there is no circular dependency
with the offsets compilation itself.  The old _Z_HEAP_SIZE manual
sizeof and BUILD_ASSERT scaffolding in heap.c are removed.

gen_offset_header.py is updated to accept multiple input object files
so that the heap constants object can coexist with the per-arch offsets
object in the same offsets library.  COMMAND_EXPAND_LISTS is added to
the offsets generation custom command so that CMake correctly expands
the $<TARGET_OBJECTS:> generator expression into separate arguments
when the offsets library contains more than one object file.

Signed-off-by: Nicolas Pitre <npitre@baylibre.com>

Author: Nicolas Pitre

CMakeLists.txt

@@ -1048,6 +1048,8 @@ target_include_directories(${OFFSETS_LIB} PRIVATE
 # Make sure that LTO will never be enabled when compiling offsets.c
 set_source_files_properties(${OFFSETS_C_PATH} PROPERTIES COMPILE_OPTIONS $<TARGET_PROPERTY:compiler,prohibit_lto>)
 
+target_sources(${OFFSETS_LIB} PRIVATE ${ZEPHYR_BASE}/lib/heap/heap_constants.c)
+
 target_link_libraries(${OFFSETS_LIB} zephyr_interface)
 add_dependencies(zephyr_interface
   ${SYSCALL_LIST_H_TARGET}
@@ -1061,6 +1063,7 @@ add_custom_command(
   COMMAND ${PYTHON_EXECUTABLE} ${ZEPHYR_BASE}/scripts/build/gen_offset_header.py
   -i $<TARGET_OBJECTS:${OFFSETS_LIB}>
   -o ${OFFSETS_H_PATH}
+  COMMAND_EXPAND_LISTS
   DEPENDS
   ${OFFSETS_LIB}
   $<TARGET_OBJECTS:${OFFSETS_LIB}>

include/zephyr/kernel.h

@@ -6108,50 +6108,55 @@ void *k_heap_realloc(struct k_heap *h, void *ptr, size_t bytes, k_timeout_t time
  */
 void k_heap_free(struct k_heap *h, void *mem) __attribute_nonnull(1);
 
-/* Minimum heap sizes needed to return a successful 1-byte allocation.
- * Assumes a chunk aligned (8 byte) memory buffer.
+/*
+ * Heap sizing constants computed at build time from actual struct layouts
+ * in lib/heap/heap_constants.c via the gen_offset mechanism.
  */
-#ifdef CONFIG_SYS_HEAP_RUNTIME_STATS
-#define Z_HEAP_MIN_SIZE ((sizeof(void *) > 4) ? 80 : 52)
-#else
-#define Z_HEAP_MIN_SIZE ((sizeof(void *) > 4) ? 56 : 44)
-#endif /* CONFIG_SYS_HEAP_RUNTIME_STATS */
+#if __has_include(<zephyr/offsets.h>)
+#include <zephyr/offsets.h>
+#endif
+
+/* chunk0 size in bytes for nb buckets */
+#define _Z_HEAP_C0(nb) \
+	ROUND_UP(___z_heap_struct_SIZEOF + \
+		 (nb) * ___z_heap_bucket_SIZEOF, ___z_heap_chunk_unit_SIZEOF)
 
-/* Size of `struct z_heap` */
-#define _Z_HEAP_SIZE                                                                               \
-	((4 * sizeof(uint32_t)) +                                                                  \
-	 (3 * (IS_ENABLED(CONFIG_SYS_HEAP_RUNTIME_STATS) ? sizeof(size_t) : 0)))
+/* Allocation chunk size in bytes */
+#define _Z_HEAP_AC(ab) \
+	ROUND_UP(___z_heap_hdr_SIZEOF + (ab), ___z_heap_chunk_unit_SIZEOF)
 
-/* Number of buckets required to store @a bytes */
-#define _Z_HEAP_NUM_BUCKETS(bytes) ((31 - __builtin_clz((bytes / 8) - 1)) + 1)
+/* Total heap size in chunk units */
+#define _Z_HEAP_SZ(nb, ab) \
+	((_Z_HEAP_C0(nb) + _Z_HEAP_AC(ab)) / ___z_heap_chunk_unit_SIZEOF)
 
-/* Number of bytes consumed by buckets */
-#define _Z_HEAP_BUCKETS_SIZE(bytes) (_Z_HEAP_NUM_BUCKETS(bytes) * sizeof(uint32_t))
+/* Bucket count from heap size in chunk units (mirrors bucket_idx() + 1) */
+#define _Z_HEAP_NB(sz) \
+	(32 - __builtin_clz((unsigned int)((sz) - \
+	 ___z_heap_min_chunk_SIZEOF + 1)))
+
+/* 3-round convergent iteration starting from 1 bucket */
+#define _Z_HEAP_NB1(ab) _Z_HEAP_NB(_Z_HEAP_SZ(1, ab))
+#define _Z_HEAP_NB2(ab) _Z_HEAP_NB(_Z_HEAP_SZ(_Z_HEAP_NB1(ab), ab))
+#define _Z_HEAP_NB3(ab) _Z_HEAP_NB(_Z_HEAP_SZ(_Z_HEAP_NB2(ab), ab))
 
 /**
  * @brief Minimum heap size required for allocating a given size
  *
  * Heaps store metadata at the start of the provided array, resulting in a
  * heap declaration of N bytes having an actual allocation capacity of less
- * than N bytes. This macro approximates how much overhead in bytes the metadata
- * consumes, allowing for real allocations closer to the requested size.
- *
- * Assumes small heaps, since for large heaps the importance of tuning single bytes
- * is small.
- *
- * The parameters considered:
- *   Size of the header "struct z_heap"
- *   Buckets holding chunk metadata
- *   Free heap chunk
- *   End chunk
- *   Chunk metadata for single allocation
+ * than N bytes.  This macro returns the exact heap buffer size needed to
+ * satisfy a single allocation of @a alloc_bytes bytes.
+ * A chunk aligned (8 byte) memory buffer is assumed.
  *
  * @param alloc_bytes Size of a desired allocation
  *
- * @return Approximate size of the heap required to allocate @a alloc_bytes
+ * @return Size of the heap required to allocate @a alloc_bytes
  */
 #define Z_HEAP_MIN_SIZE_FOR(alloc_bytes) \
-	((alloc_bytes) + _Z_HEAP_SIZE + _Z_HEAP_BUCKETS_SIZE(alloc_bytes) + (3 * 8))
+	(_Z_HEAP_C0(_Z_HEAP_NB3(alloc_bytes)) + \
+	 _Z_HEAP_AC(alloc_bytes) + ___z_heap_ftr_SIZEOF)
+
+#define Z_HEAP_MIN_SIZE Z_HEAP_MIN_SIZE_FOR(1)
 
 /**
  * @brief Define a static k_heap in the specified linker section

lib/heap/heap.c

@@ -13,8 +13,6 @@
 #include <sanitizer/msan_interface.h>
 #endif
 
-/* Validate the `kernel.h` macro */
-BUILD_ASSERT(_Z_HEAP_SIZE == sizeof(struct z_heap), "Incorrect _Z_HEAP_SIZE value");
 
 #ifdef CONFIG_SYS_HEAP_RUNTIME_STATS
 static inline void increase_allocated_bytes(struct z_heap *h, size_t num_bytes)

lib/heap/heap_constants.c

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2026 BayLibre SAS
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Build-time computation of heap constants from actual struct layouts.
+ * Compiled as part of the offsets library so that the generated offsets.h
+ * header provides heap sizing values derived from real structure sizes,
+ * eliminating manual synchronization of magic numbers in kernel.h.
+ *
+ * The heap layout for a single allocation looks like:
+ *
+ *   [     chunk0: struct z_heap + buckets     ]  [  alloc chunk  ]  [ftr]
+ *                                                 |              |
+ *                                                hdr    data   (trailer)
+ *
+ * Each region is sized as follows:
+ *
+ *   chunk0  = ROUND_UP(sizeof(struct z_heap) + nb * bucket_size, CHUNK_UNIT)
+ *   alloc   = ROUND_UP(chunk_header_bytes + alloc_bytes, CHUNK_UNIT)
+ *   ftr     = heap_footer_bytes  (end marker, not chunk-aligned)
+ *
+ * The number of buckets (nb) depends on the total heap size in chunk
+ * units, creating a circular dependency that is resolved by iterating
+ * from 1 bucket until convergence (3 rounds always suffice).
+ *
+ * The individual component sizes are emitted as symbols so that
+ * kernel.h can compute exact heap sizes without any magic numbers.
+ */
+
+#include <gen_offset.h>
+#include <zephyr/kernel.h>
+#include "heap.h"
+
+/*
+ * Determine whether the heap uses big (8-byte) or small (4-byte) chunk
+ * headers and footers.  This mirrors big_heap_chunks() in heap.h: for
+ * the minimum-size computation the heap is always tiny, so the runtime
+ * size threshold never triggers — only Kconfig and pointer width matter.
+ */
+#ifdef CONFIG_SYS_HEAP_SMALL_ONLY
+#define _IS_BIG 0
+#elif defined(CONFIG_SYS_HEAP_BIG_ONLY)
+#define _IS_BIG 1
+#else
+#define _IS_BIG (sizeof(void *) > 4)
+#endif
+
+#define _HDR (_IS_BIG ? 8 : 4)	/* chunk_header_bytes */
+#define _FTR (_IS_BIG ? 8 : 4)	/* heap_footer_bytes  */
+
+/* Round up to chunk units (compile-time version of chunksz()) */
+#define _CHUNKSZ(n) (((n) + CHUNK_UNIT - 1U) / CHUNK_UNIT)
+
+/* min_chunk_size: smallest allocatable chunk (in chunk units) */
+#define _MINC  _CHUNKSZ(_HDR + 1)
+
+/* --- emit symbols into offsets.h --- */
+
+GEN_ABS_SYM_BEGIN(_HeapConstantAbsSyms)
+
+GEN_ABSOLUTE_SYM(___z_heap_struct_SIZEOF, sizeof(struct z_heap));
+
+GEN_ABSOLUTE_SYM(___z_heap_bucket_SIZEOF,
+	sizeof(struct z_heap_bucket));
+
+GEN_ABSOLUTE_SYM(___z_heap_chunk_unit_SIZEOF, CHUNK_UNIT);
+
+GEN_ABSOLUTE_SYM(___z_heap_hdr_SIZEOF, (unsigned int)_HDR);
+
+GEN_ABSOLUTE_SYM(___z_heap_ftr_SIZEOF, (unsigned int)_FTR);
+
+GEN_ABSOLUTE_SYM(___z_heap_min_chunk_SIZEOF, (unsigned int)_MINC);
+
+GEN_ABS_SYM_END

scripts/build/gen_offset_header.py

@@ -6,8 +6,8 @@
 #
 
 """
-This script scans a specified object file and generates a header file
-that defined macros for the offsets of various found structure members
+This script scans one or more specified object files and generates a header
+file that defined macros for the offsets of various found structure members
 (particularly symbols ending with ``_OFFSET`` or ``_SIZEOF``), primarily
 intended for use in assembly code.
 """
@@ -27,7 +27,7 @@ def get_symbol_table(obj):
     raise LookupError("Could not find symbol table")
 
 
-def gen_offset_header(input_name, input_file, output_file):
+def gen_offset_header(input_files, output_file):
     include_guard = "__GEN_OFFSETS_H__"
     output_file.write(
         f"""/* THIS FILE IS AUTO GENERATED.  PLEASE DO NOT EDIT.
@@ -41,19 +41,21 @@ def gen_offset_header(input_name, input_file, output_file):
 #define {include_guard}\n\n"""
     )
 
-    obj = ELFFile(input_file)
-    for sym in get_symbol_table(obj).iter_symbols():
-        if isinstance(sym.name, bytes):
-            sym.name = str(sym.name, 'ascii')
+    for input_path in input_files:
+        with open(input_path, 'rb') as input_file:
+            obj = ELFFile(input_file)
+            for sym in get_symbol_table(obj).iter_symbols():
+                if isinstance(sym.name, bytes):
+                    sym.name = str(sym.name, 'ascii')
 
-        if not sym.name.endswith(('_OFFSET', '_SIZEOF')):
-            continue
-        if sym.entry['st_shndx'] != 'SHN_ABS':
-            continue
-        if sym.entry['st_info']['bind'] != 'STB_GLOBAL':
-            continue
+                if not sym.name.endswith(('_OFFSET', '_SIZEOF')):
+                    continue
+                if sym.entry['st_shndx'] != 'SHN_ABS':
+                    continue
+                if sym.entry['st_info']['bind'] != 'STB_GLOBAL':
+                    continue
 
-        output_file.write(f"#define {sym.name} 0x{sym.entry['st_value']:x}\n")
+                output_file.write(f"#define {sym.name} 0x{sym.entry['st_value']:x}\n")
 
     output_file.write(f"\n#endif /* {include_guard} */\n")
 
@@ -67,12 +69,12 @@ def gen_offset_header(input_name, input_file, output_file):
         allow_abbrev=False,
     )
 
-    parser.add_argument("-i", "--input", required=True, help="Input object file")
+    parser.add_argument("-i", "--input", required=True, nargs='+', help="Input object file(s)")
     parser.add_argument("-o", "--output", required=True, help="Output header file")
 
     args = parser.parse_args()
 
-    with open(args.input, 'rb') as input_file, open(args.output, 'w') as output_file:
-        ret = gen_offset_header(args.input, input_file, output_file)
+    with open(args.output, 'w') as output_file:
+        ret = gen_offset_header(args.input, output_file)
 
     sys.exit(ret)