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/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),