Add kernel memory functions & other memory-related changes (#590)

New Features

- Added policy-based memory allocation APIs with capability flags and optional alignment: `memory_alloc_with_policy`, `memory_realloc_with_policy`, `memory_calloc_with_policy`, and `memory_free`.
- Switched heap memory reporting to `memory_print_stats`.

Bug Fixes

- Improved allocation robustness with capability fallback behavior.
- Added overflow-safe handling for aligned zero-initialized allocations.
- Tightened const-correctness for generated device-tree device arrays.

Tests

- Added unit tests for default policy, alignment, zero-initialization, realloc preservation, freeing, and memory stats reporting.

TactilityKernel/include/tactility/kernel_init.h

@@ -14,7 +14,7 @@ extern "C" {
  * @param dts_devices The list of generated devices from the devicetree. The array must be terminated with DTS_DEVICE_TERMINATOR. Non-null parameter.
  * @return ERROR_NONE on success, otherwise an error code
  */
-error_t kernel_init(struct Module* dts_modules[], struct DtsDevice dts_devices[]);
+error_t kernel_init(struct Module* const dts_modules[], const struct DtsDevice dts_devices[]);
 
 #ifdef __cplusplus
 }

TactilityKernel/include/tactility/memory.h

@@ -1,10 +1,114 @@
 #pragma once
 
+#include <stddef.h>
+#include <stdint.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-void memory_trace();
+/** Capability flags that describe what a memory allocation needs or prefers. */
+enum MemoryCapability {
+    /** Internal memory (non-external/non-PSRAM) memory. */
+    MEMORY_CAPABILITY_INTERNAL   = 1u << 0,
+    /** External memory (e.g. PSRAM/SPIRAM). */
+    MEMORY_CAPABILITY_EXTERNAL   = 1u << 1,
+    /** Usable for code execution. */
+    MEMORY_CAPABILITY_EXECUTABLE = 1u << 2,
+    /** Usable as a DMA source/destination. */
+    MEMORY_CAPABILITY_DMA        = 1u << 3,
+    /** Usable for SIMD instructions. */
+    MEMORY_CAPABILITY_SIMD       = 1u << 4,
+};
+
+/**
+ * @brief Describes the constraints an allocation must (or should) satisfy.
+ *
+ * `required` capabilities must all be satisfied or the allocation fails. `desired`
+ * capabilities are attempted alongside `required`, but implementations fall back to
+ * `required`-only if `required | desired` together can't be satisfied.
+ */
+struct MemoryPolicy {
+    /** A bitset of MemoryCapability flags that are required during allocation. */
+    uint16_t required;
+    /** A bitset of MemoryCapability flags that are preferable (but optional) during allocation. */
+    uint16_t desired;
+    /** Alignment (in bytes) of the returned pointer, or 0 for the platform default. Must be a power of 2. */
+    size_t alignment;
+};
+
+/** The default policy: no required/desired capabilities, no alignment requirement. */
+extern const struct MemoryPolicy MEMORY_POLICY_DEFAULT;
+
+/**
+ * @brief Logs current heap usage (internal and external, when applicable).
+ * No-op on platforms without heap capability tracking.
+ */
+void memory_print_stats();
+
+/**
+ * @brief Allocates memory that satisfies the given policy.
+ * @param[in] size number of bytes to allocate
+ * @param[in] policy the allocation constraints
+ * @return the allocated memory, or NULL on failure
+ */
+void* memory_alloc_with_policy(size_t size, const struct MemoryPolicy* policy);
+
+/**
+ * @brief Resizes a previous allocation, preserving its contents up to the smaller of the old and new size.
+ * @warning policy->alignment is not guaranteed to be preserved across a realloc - it is only
+ * honored on fresh allocations (memory_alloc_with_policy()/memory_calloc_with_policy()).
+ * @param[in] ptr memory previously returned by memory_alloc_with_policy(), memory_calloc_with_policy(),
+ * or memory_realloc_with_policy(), or NULL to allocate a new block
+ * @param[in] size new memory size in bytes
+ * @param[in] policy the policy for the new allocation
+ * @return the (possibly moved) allocated memory, or NULL on failure - in which case ptr is left untouched
+ */
+void* memory_realloc_with_policy(void* ptr, size_t size, const struct MemoryPolicy* policy);
+
+/**
+ * @brief Allocates zero-initialized memory that satisfies the given policy.
+ * @param[in] count number of elements
+ * @param[in] size size of each element in bytes
+ * @param[in] policy the allocation constraints
+ * @return the allocated memory, or NULL on failure
+ */
+void* memory_calloc_with_policy(size_t count, size_t size, const struct MemoryPolicy* policy);
+
+/**
+ * @brief Allocates memory using MEMORY_POLICY_DEFAULT.
+ * @param[in] size number of bytes to allocate
+ * @return the allocated memory, or NULL on failure
+ */
+inline void* memory_alloc(size_t size) {
+    return memory_alloc_with_policy(size, &MEMORY_POLICY_DEFAULT);
+}
+
+/**
+ * @brief Allocates zero-initialized memory using MEMORY_POLICY_DEFAULT.
+ * @param[in] count number of elements
+ * @param[in] size size of each element in bytes
+ * @return the allocated memory, or NULL on failure
+ */
+inline void* memory_calloc(size_t count, size_t size) {
+    return memory_calloc_with_policy(count, size, &MEMORY_POLICY_DEFAULT);
+}
+
+/**
+ * @brief Resizes a previous allocation using MEMORY_POLICY_DEFAULT. See memory_realloc_with_policy().
+ * @param[in] ptr memory previously returned by one of the memory_* allocation functions, or NULL
+ * @param[in] size new memory size in bytes
+ * @return the (possibly moved) allocated memory, or NULL on failure - in which case ptr is left untouched
+ */
+inline void* memory_realloc(void* ptr, size_t size) {
+    return memory_realloc_with_policy(ptr, size, &MEMORY_POLICY_DEFAULT);
+}
+
+/**
+ * @brief Frees memory previously returned by one of the memory_* allocation functions.
+ * @param[in] ptr the memory to free, or NULL (a no-op)
+ */
+void memory_free(void* ptr);
 
 #ifdef __cplusplus
 }

TactilityKernel/source/kernel_init.cpp

@@ -43,7 +43,7 @@ Module root_module = {
     .internal = nullptr
 };
 
-error_t kernel_init(Module* dts_modules[], DtsDevice dts_devices[]) {
+error_t kernel_init(Module* const dts_modules[], const DtsDevice dts_devices[]) {
     LOG_I(TAG, "init");
 
     if (module_construct_add_start(&root_module) != ERROR_NONE) {
@@ -51,7 +51,7 @@ error_t kernel_init(Module* dts_modules[], DtsDevice dts_devices[]) {
         return ERROR_RESOURCE;
     }
 
-    Module** dts_module = dts_modules;
+    Module* const* dts_module = dts_modules;
     while (*dts_module != nullptr) {
         if (module_construct_add_start(*dts_module) != ERROR_NONE) {
             LOG_E(TAG, "dts module init failed: %s", (*dts_module)->name);
@@ -60,7 +60,7 @@ error_t kernel_init(Module* dts_modules[], DtsDevice dts_devices[]) {
         dts_module++;
     }
 
-    DtsDevice* dts_device = dts_devices;
+    const DtsDevice* dts_device = dts_devices;
     while (dts_device->device != nullptr) {
         if (dts_device->status == DTS_DEVICE_STATUS_OKAY) {
             if (device_construct_add_start(dts_device->device, dts_device->compatible) != ERROR_NONE) {

TactilityKernel/source/memory.cpp

@@ -9,7 +9,13 @@ constexpr auto* TAG = "memory";
 
 extern "C" {
 
-void memory_trace() {
+const struct MemoryPolicy MEMORY_POLICY_DEFAULT = {
+    .required = 0,
+    .desired = 0,
+    .alignment = 0,
+};
+
+void memory_print_stats() {
 #ifdef ESP_PLATFORM
     size_t heap_free = heap_caps_get_free_size(MALLOC_CAP_INTERNAL);
     size_t heap_total = heap_caps_get_total_size(MALLOC_CAP_INTERNAL);

TactilityKernel/source/memory_esp32.cpp

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+#ifdef ESP_PLATFORM
+
+#include <tactility/memory.h>
+
+#include <esp_heap_caps.h>
+
+namespace {
+
+uint32_t toHeapCaps(uint16_t capabilityFlags) {
+    uint32_t caps = 0;
+    if (capabilityFlags & MEMORY_CAPABILITY_INTERNAL) caps |= MALLOC_CAP_INTERNAL;
+    if (capabilityFlags & MEMORY_CAPABILITY_EXTERNAL) caps |= MALLOC_CAP_SPIRAM;
+    if (capabilityFlags & MEMORY_CAPABILITY_EXECUTABLE) caps |= MALLOC_CAP_EXEC;
+    if (capabilityFlags & MEMORY_CAPABILITY_DMA) caps |= MALLOC_CAP_DMA;
+    if (capabilityFlags & MEMORY_CAPABILITY_SIMD) caps |= MALLOC_CAP_SIMD;
+    return caps;
+}
+
+} // namespace
+
+extern "C" {
+
+void* memory_alloc_with_policy(size_t size, const struct MemoryPolicy* policy) {
+    uint32_t required_caps = toHeapCaps(policy->required);
+    uint32_t desired_caps = toHeapCaps(policy->desired);
+
+    void* ptr;
+    if (policy->alignment > 0) {
+        ptr = heap_caps_aligned_alloc(policy->alignment, size, required_caps | desired_caps);
+        if (ptr == nullptr && desired_caps != 0) {
+            // Desired caps couldn't be satisfied alongside the required ones - retry with
+            // required only, since desired is explicitly optional.
+            ptr = heap_caps_aligned_alloc(policy->alignment, size, required_caps);
+        }
+    } else {
+        ptr = heap_caps_malloc(size, required_caps | desired_caps);
+        if (ptr == nullptr && desired_caps != 0) {
+            ptr = heap_caps_malloc(size, required_caps);
+        }
+    }
+    return ptr;
+}
+
+void* memory_realloc_with_policy(void* ptr, size_t size, const struct MemoryPolicy* policy) {
+    uint32_t required_caps = toHeapCaps(policy->required);
+    uint32_t desired_caps = toHeapCaps(policy->desired);
+
+    // No aligned-realloc counterpart in the heap_caps API - policy->alignment is only honored
+    // on fresh allocations (memory_alloc_with_policy/memory_calloc_with_policy).
+    void* result = heap_caps_realloc(ptr, size, required_caps | desired_caps);
+    if (result == nullptr && desired_caps != 0) {
+        result = heap_caps_realloc(ptr, size, required_caps);
+    }
+    return result;
+}
+
+void* memory_calloc_with_policy(size_t count, size_t size, const struct MemoryPolicy* policy) {
+    uint32_t required_caps = toHeapCaps(policy->required);
+    uint32_t desired_caps = toHeapCaps(policy->desired);
+
+    void* ptr;
+    if (policy->alignment > 0) {
+        ptr = heap_caps_aligned_calloc(policy->alignment, count, size, required_caps | desired_caps);
+        if (ptr == nullptr && desired_caps != 0) {
+            ptr = heap_caps_aligned_calloc(policy->alignment, count, size, required_caps);
+        }
+    } else {
+        ptr = heap_caps_calloc(count, size, required_caps | desired_caps);
+        if (ptr == nullptr && desired_caps != 0) {
+            ptr = heap_caps_calloc(count, size, required_caps);
+        }
+    }
+    return ptr;
+}
+
+void memory_free(void* ptr) {
+    heap_caps_free(ptr);
+}
+
+} // extern "C"
+
+#endif // ESP_PLATFORM

TactilityKernel/source/memory_posix.cpp

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+#ifndef ESP_PLATFORM
+
+#include <tactility/memory.h>
+
+#include <cstdint>
+#include <cstdlib>
+#include <cstring>
+
+namespace {
+
+// posix_memalign requires a power-of-2 alignment that's at least sizeof(void*).
+size_t normalizeAlignment(uint8_t alignment) {
+    size_t result = alignment;
+    if (result < sizeof(void*)) {
+        result = sizeof(void*);
+    }
+    return result;
+}
+
+} // namespace
+
+extern "C" {
+
+// MEMORY_CAP_* flags are meaningless on the desktop simulator (no capability-restricted memory regions)
+// policy->required/desired are intentionally ignored here.
+void* memory_alloc_with_policy(size_t size, const struct MemoryPolicy* policy) {
+    if (policy->alignment > 0) {
+        void* ptr = nullptr;
+        if (posix_memalign(&ptr, normalizeAlignment(policy->alignment), size) != 0) {
+            return nullptr;
+        }
+        return ptr;
+    }
+    return malloc(size);
+}
+
+void* memory_realloc_with_policy(void* ptr, size_t size, const struct MemoryPolicy* policy) {
+    // Alignment can't be preserved across a POSIX realloc; only honored on fresh allocations
+    // (memory_alloc_with_policy/memory_calloc_with_policy).
+    return realloc(ptr, size);
+}
+
+void* memory_calloc_with_policy(size_t count, size_t size, const struct MemoryPolicy* policy) {
+    if (policy->alignment > 0) {
+        size_t total_size = count * size;
+        if (count != 0 && total_size / count != size) {
+            // count * size overflowed - reject rather than under-allocating.
+            return nullptr;
+        }
+
+        void* ptr = nullptr;
+        if (posix_memalign(&ptr, normalizeAlignment(policy->alignment), total_size) != 0) {
+            return nullptr;
+        }
+        memset(ptr, 0, total_size);
+        return ptr;
+    }
+    return calloc(count, size);
+}
+
+void memory_free(void* ptr) {
+    free(ptr);
+}
+
+} // extern "C"
+
+#endif // !ESP_PLATFORM

TactilityKernel/source/symbols.c

@@ -37,6 +37,7 @@
 #include <tactility/error.h>
 #include <tactility/filesystem/file_system.h>
 #include <tactility/filesystem/file_mutex.h>
+#include <tactility/memory.h>
 #include <tactility/module.h>
 #include <tactility/wifi_auto_scan.h>
 #include <tactility/service/service_instance.h>
@@ -175,6 +176,13 @@ const struct ModuleSymbol KERNEL_SYMBOLS[] = {
     DEFINE_MODULE_SYMBOL(file_system_unmount),
     DEFINE_MODULE_SYMBOL(file_system_is_mounted),
     DEFINE_MODULE_SYMBOL(file_system_get_path),
+    // memory
+    DEFINE_MODULE_SYMBOL(MEMORY_POLICY_DEFAULT),
+    DEFINE_MODULE_SYMBOL(memory_print_stats),
+    DEFINE_MODULE_SYMBOL(memory_alloc_with_policy),
+    DEFINE_MODULE_SYMBOL(memory_realloc_with_policy),
+    DEFINE_MODULE_SYMBOL(memory_calloc_with_policy),
+    DEFINE_MODULE_SYMBOL(memory_free),
     // drivers/gpio_controller
     DEFINE_MODULE_SYMBOL(gpio_descriptor_acquire),
     DEFINE_MODULE_SYMBOL(gpio_descriptor_release),