Kernel improvements (#468)

* **New Features**
  * Plugin-style modules for platforms and devices with start/stop lifecycle and a runtime-consumable device tree array.

* **Refactor**
  * Consolidated initialization into a kernel/module startup flow.
  * Generated devicetree artifacts moved to the build Generated directory.

* **Changes**
  * Removed legacy no-op registration hooks and I2C lock/unlock wrappers.
  * Driver ownership and private state moved to explicit module/owner model.
  * Added ERROR_NOT_ALLOWED error code.

TactilityKernel/Include/tactility/concurrent/recursive_mutex.h

@@ -15,6 +15,7 @@ struct RecursiveMutex {
 };
 
 inline static void recursive_mutex_construct(struct RecursiveMutex* mutex) {
+    check(mutex->handle == NULL);
     mutex->handle = xSemaphoreCreateRecursiveMutex();
 }
 

TactilityKernel/Include/tactility/device.h

@@ -16,6 +16,7 @@ extern "C" {
 #include <tactility/concurrent/mutex.h>
 
 struct Driver;
+struct DevicePrivate;
 
 /** Enables discovering devices of the same type */
 struct DeviceType {
@@ -46,10 +47,20 @@ struct Device {
             bool added : 1;
         } state;
         /** Private data */
-        void* data;
+        struct DevicePrivate* device_private;
     } internal;
 };
 
+/**
+ * Holds a device pointer and a compatible string.
+ * The device must not be constructed, added or started yet.
+ * This is used by the devicetree code generator and the application init sequence.
+ */
+struct CompatibleDevice {
+    struct Device* device;
+    const char* compatible;
+};
+
 /**
  * Initialize the properties of a device.
  *

TactilityKernel/Include/tactility/driver.h

@@ -11,6 +11,8 @@ extern "C" {
 
 struct Device;
 struct DeviceType;
+struct Module;
+struct DriverPrivate;
 
 struct Driver {
     /** The driver name */
@@ -25,11 +27,10 @@ struct Driver {
     const void* api;
     /** Which type of devices this driver creates (can be NULL) */
     const struct DeviceType* deviceType;
+    /** The module that owns this driver. When it is NULL, the system owns the driver and it cannot be removed from registration. */
+    const struct Module* owner;
     /** Internal data */
-    struct {
-        /** Contains private data */
-        void* data;
-    } internal;
+    struct DriverPrivate* driver_private;
 };
 
 error_t driver_construct(struct Driver* driver);

TactilityKernel/Include/tactility/error.h

@@ -22,6 +22,7 @@ typedef int error_t;
 #define ERROR_TIMEOUT 8
 #define ERROR_OUT_OF_MEMORY 9
 #define ERROR_NOT_SUPPORTED 10
+#define ERROR_NOT_ALLOWED 11
 
 /** Convert an error_t to a human-readable text. Useful for logging. */
 const char* error_to_string(error_t error);

TactilityKernel/Include/tactility/kernel_init.h

@@ -0,0 +1,22 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <tactility/device.h>
+#include <tactility/error.h>
+#include <tactility/module.h>
+
+/**
+ * Initialize the kernel with platform and device modules, and a device tree.
+ * @param platform_module The platform module to start. This module should not be constructed yet.
+ * @param device_module The device module to start. This module should not be constructed yet.
+ * @param devicetree_devices The list of generated devices from the devicetree. The array must be terminated by an entry { NULL, NULL }
+ * @return ERROR_NONE on success, otherwise an error code
+ */
+error_t kernel_init(struct Module* platform_module, struct Module* device_module, struct CompatibleDevice devicetree_devices[]);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/tactility/module.h

@@ -0,0 +1,101 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "error.h"
+#include <stdbool.h>
+
+struct ModuleParent;
+struct ModuleParentPrivate;
+
+/**
+ * A module is a collection of drivers or other functionality that can be loaded and unloaded at runtime.
+ */
+struct Module {
+    /**
+     * The name of the module, for logging/debugging purposes
+     * Should never be NULL.
+     */
+    const char* name;
+
+    /**
+     * A function to initialize the module.
+     * Should never be NULL.
+     * This can be used to load drivers, initialize hardware, etc.
+     * @return ERROR_NONE if successful
+     */
+    error_t (*start)(void);
+
+    /**
+     * Deinitializes the module.
+     * Should never be NULL.
+     * @return ERROR_NONE if successful
+     */
+    error_t (*stop)(void);
+
+    struct {
+        bool started;
+        struct ModuleParent* parent;
+    } internal;
+};
+
+/**
+ * A module parent is a collection of modules that can be loaded and unloaded at runtime.
+ */
+struct ModuleParent {
+    /** The name of the parent module, for logging/debugging purposes */
+    const char* name;
+    struct ModuleParentPrivate* module_parent_private;
+};
+
+/**
+ * @brief Initialize the module parent.
+ * @warn This function does no validation on input or state.
+ * @param parent parent module
+ * @return ERROR_NONE if successful, ERROR_OUT_OF_MEMORY if allocation fails
+ */
+error_t module_parent_construct(struct ModuleParent* parent);
+
+/**
+ * @brief Deinitialize the module parent. Must have no children when calling this.
+ * @warn This function does no validation on input.
+ * @param parent parent module
+ * @return ERROR_NONE if successful or ERROR_INVALID_STATE if the parent has children
+ */
+error_t module_parent_destruct(struct ModuleParent* parent);
+
+/**
+ * @brief Set the parent of the module.
+ * @warning must call before module_start()
+ * @param module module
+ * @param parent nullable parent module
+ * @return ERROR_NONE if successful, ERROR_INVALID_STATE if the module is already started
+ */
+error_t module_set_parent(struct Module* module, struct ModuleParent* parent);
+
+/**
+ * @brief Start the module.
+ * @param module module
+ * @return ERROR_NONE if already started, ERROR_INVALID_STATE if the module doesn't have a parent, or otherwise it returns the result of the module's start function
+ */
+error_t module_start(struct Module* module);
+
+/**
+ * @brief Check if the module is started.
+ * @param module module to check
+ * @return true if the module is started, false otherwise
+ */
+bool module_is_started(struct Module* module);
+
+/**
+ * @brief Stop the module.
+ * @param module module
+ * @return ERROR_NONE if successful or if the module wasn't started, or otherwise it returns the result of the module's stop function
+ */
+error_t module_stop(struct Module* module);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Source/device.cpp

@@ -13,7 +13,7 @@
 
 #define TAG LOG_TAG(device)
 
-struct DeviceData {
+struct DevicePrivate {
     std::vector<Device*> children;
 };
 
@@ -42,11 +42,11 @@ extern "C" {
 #define ledger_lock() mutex_lock(&ledger.mutex)
 #define ledger_unlock() mutex_unlock(&ledger.mutex)
 
-#define get_device_data(device) static_cast<DeviceData*>(device->internal.data)
+#define get_device_private(device) static_cast<DevicePrivate*>(device->internal.device_private)
 
 error_t device_construct(Device* device) {
-    device->internal.data = new(std::nothrow) DeviceData;
-    if (device->internal.data == nullptr) {
+    device->internal.device_private = new(std::nothrow) DevicePrivate;
+    if (device->internal.device_private == nullptr) {
         return ERROR_OUT_OF_MEMORY;
     }
     LOG_I(TAG, "construct %s", device->name);
@@ -58,13 +58,13 @@ error_t device_destruct(Device* device) {
     if (device->internal.state.started || device->internal.state.added) {
         return ERROR_INVALID_STATE;
     }
-    if (!get_device_data(device)->children.empty()) {
+    if (!get_device_private(device)->children.empty()) {
         return ERROR_INVALID_STATE;
     }
     LOG_I(TAG, "destruct %s", device->name);
     mutex_destruct(&device->internal.mutex);
-    delete get_device_data(device);
-    device->internal.data = nullptr;
+    delete get_device_private(device);
+    device->internal.device_private = nullptr;
     return ERROR_NONE;
 }
 
@@ -72,14 +72,14 @@ error_t device_destruct(Device* device) {
 static void device_add_child(struct Device* device, struct Device* child) {
     device_lock(device);
     assert(device->internal.state.added);
-    get_device_data(device)->children.push_back(child);
+    get_device_private(device)->children.push_back(child);
     device_unlock(device);
 }
 
 /** Remove a child from the list of children */
 static void device_remove_child(struct Device* device, struct Device* child) {
     device_lock(device);
-    auto* parent_data = get_device_data(device);
+    auto* parent_data = get_device_private(device);
     const auto iterator = std::ranges::find(parent_data->children, child);
     if (iterator != parent_data->children.end()) {
         parent_data->children.erase(iterator);
@@ -251,7 +251,7 @@ void for_each_device(void* callback_context, bool(*on_device)(Device* device, vo
 }
 
 void for_each_device_child(Device* device, void* callbackContext, bool(*on_device)(struct Device* device, void* context)) {
-    auto* data = get_device_data(device);
+    auto* data = get_device_private(device);
     for (auto* child_device : data->children) {
         if (!on_device(child_device, callbackContext)) {
             break;

TactilityKernel/Source/driver.cpp

@@ -12,16 +12,16 @@
 
 #define TAG LOG_TAG(driver)
 
-struct DriverInternalData {
+struct DriverPrivate {
     Mutex mutex { 0 };
     int use_count = 0;
     bool destroying = false;
 
-    DriverInternalData() {
+    DriverPrivate() {
         mutex_construct(&mutex);
     }
 
-    ~DriverInternalData() {
+    ~DriverPrivate() {
         mutex_destruct(&mutex);
     }
 };
@@ -54,9 +54,9 @@ static DriverLedger& get_ledger() {
 
 #define ledger get_ledger()
 
-#define driver_internal_data(driver) static_cast<DriverInternalData*>(driver->internal.data)
-#define driver_lock(driver) mutex_lock(&driver_internal_data(driver)->mutex);
-#define driver_unlock(driver) mutex_unlock(&driver_internal_data(driver)->mutex);
+#define get_driver_private(driver) static_cast<DriverPrivate*>(driver->driver_private)
+#define driver_lock(driver) mutex_lock(&get_driver_private(driver)->mutex);
+#define driver_unlock(driver) mutex_unlock(&get_driver_private(driver)->mutex);
 
 static void driver_add(Driver* driver) {
     LOG_I(TAG, "add %s", driver->name);
@@ -83,8 +83,8 @@ static error_t driver_remove(Driver* driver) {
 extern "C" {
 
 error_t driver_construct(Driver* driver) {
-    driver->internal.data = new(std::nothrow) DriverInternalData;
-    if (driver->internal.data == nullptr) {
+    driver->driver_private = new(std::nothrow) DriverPrivate;
+    if (driver->driver_private == nullptr) {
         return ERROR_OUT_OF_MEMORY;
     }
     driver_add(driver);
@@ -93,19 +93,25 @@ error_t driver_construct(Driver* driver) {
 
 error_t driver_destruct(Driver* driver) {
     driver_lock(driver);
-    if (driver_internal_data(driver)->use_count != 0 || driver_internal_data(driver)->destroying) {
+    // No module means the system owns it and it cannot be destroyed
+    if (driver->owner == nullptr) {
+        driver_unlock(driver);
+        return ERROR_NOT_ALLOWED;
+    }
+    if (get_driver_private(driver)->use_count != 0 || get_driver_private(driver)->destroying) {
         driver_unlock(driver);
         return ERROR_INVALID_STATE;
     }
-    driver_internal_data(driver)->destroying = true;
-    driver_unlock(driver);
+    get_driver_private(driver)->destroying = true;
 
     if (driver_remove(driver) != ERROR_NONE) {
         LOG_W(TAG, "Failed to remove driver from ledger: %s", driver->name);
     }
 
-    delete driver_internal_data(driver);
-    driver->internal.data = nullptr;
+    driver_unlock(driver);
+    delete get_driver_private(driver);
+    driver->driver_private = nullptr;
+
     return ERROR_NONE;
 }
 
@@ -140,7 +146,7 @@ error_t driver_bind(Driver* driver, Device* device) {
     driver_lock(driver);
 
     error_t error = ERROR_NONE;
-    if (driver_internal_data(driver)->destroying || !device_is_added(device)) {
+    if (get_driver_private(driver)->destroying || !device_is_added(device)) {
         error = ERROR_INVALID_STATE;
         goto error;
     }
@@ -152,7 +158,7 @@ error_t driver_bind(Driver* driver, Device* device) {
         }
     }
 
-    driver_internal_data(driver)->use_count++;
+    get_driver_private(driver)->use_count++;
     driver_unlock(driver);
 
     LOG_I(TAG, "bound %s to %s", driver->name, device->name);
@@ -168,7 +174,7 @@ error_t driver_unbind(Driver* driver, Device* device) {
     driver_lock(driver);
 
     error_t error = ERROR_NONE;
-    if (driver_internal_data(driver)->destroying || !device_is_added(device)) {
+    if (get_driver_private(driver)->destroying || !device_is_added(device)) {
         error = ERROR_INVALID_STATE;
         goto error;
     }
@@ -180,7 +186,7 @@ error_t driver_unbind(Driver* driver, Device* device) {
         }
     }
 
-    driver_internal_data(driver)->use_count--;
+    get_driver_private(driver)->use_count--;
     driver_unlock(driver);
 
     LOG_I(TAG, "unbound %s from %s", driver->name, device->name);

TactilityKernel/Source/drivers/register.cpp

@@ -1,12 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-#include <tactility/driver.h>
-
-extern "C" {
-
-extern void register_kernel_drivers() {
-    extern Driver root_driver;
-    driver_construct(&root_driver);
-}
-
-}

TactilityKernel/Source/drivers/root.cpp

@@ -12,7 +12,8 @@ Driver root_driver = {
     .stopDevice = nullptr,
     .api = nullptr,
     .deviceType = nullptr,
-    .internal = { 0 }
+    .owner = nullptr,
+    .driver_private = nullptr
 };
 
 }

TactilityKernel/Source/error.cpp

@@ -27,6 +27,8 @@ const char* error_to_string(error_t error) {
             return "out of memory";
         case ERROR_NOT_SUPPORTED:
             return "not supported";
+        case ERROR_NOT_ALLOWED:
+            return "not allowed";
         default:
             return "unknown";
     }

TactilityKernel/Source/kernel_init.cpp

@@ -0,0 +1,61 @@
+#include <tactility/kernel_init.h>
+#include <tactility/log.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define TAG LOG_TAG(kernel)
+
+struct ModuleParent kernel_module_parent = {
+    "kernel",
+    nullptr
+};
+
+static error_t init_kernel_drivers() {
+    extern Driver root_driver;
+    if (driver_construct(&root_driver) != ERROR_NONE) return ERROR_RESOURCE;
+    return ERROR_NONE;
+}
+
+error_t kernel_init(struct Module* platform_module, struct Module* device_module, struct CompatibleDevice devicetree_devices[]) {
+    LOG_I(TAG, "init");
+
+    if (module_parent_construct(&kernel_module_parent) != ERROR_NONE) {
+        LOG_E(TAG, "init failed to create kernel module parent");
+        return ERROR_RESOURCE;
+    }
+
+    if (init_kernel_drivers() != ERROR_NONE) {
+        LOG_E(TAG, "init failed to init kernel drivers");
+        return ERROR_RESOURCE;
+    }
+
+    module_set_parent(platform_module, &kernel_module_parent);
+    if (module_start(platform_module) != ERROR_NONE) {
+        LOG_E(TAG, "init failed to start platform module");
+        return ERROR_RESOURCE;
+    }
+
+    module_set_parent(device_module, &kernel_module_parent);
+    if (module_start(device_module) != ERROR_NONE) {
+        LOG_E(TAG, "init failed to start device module");
+        return ERROR_RESOURCE;
+    }
+
+    CompatibleDevice* compatible_device = devicetree_devices;
+    while (compatible_device->device != nullptr) {
+        if (device_construct_add_start(compatible_device->device, compatible_device->compatible) != ERROR_NONE) {
+            LOG_E(TAG, "kernel_init failed to construct device: %s (%s)", compatible_device->device->name, compatible_device->compatible);
+            return ERROR_RESOURCE;
+        }
+        compatible_device++;
+    }
+
+    LOG_I(TAG, "init done");
+    return ERROR_NONE;
+};
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Source/module.cpp

@@ -0,0 +1,102 @@
+#include <vector>
+#include <algorithm>
+#include <tactility/concurrent/mutex.h>
+#include <tactility/module.h>
+
+struct ModuleParentPrivate {
+    std::vector<struct Module*> modules;
+    struct Mutex mutex = { 0 };
+};
+
+extern "C" {
+
+#pragma region module_parent
+
+error_t module_parent_construct(struct ModuleParent* parent) {
+    parent->module_parent_private = new (std::nothrow) ModuleParentPrivate();
+    if (!parent->module_parent_private) return ERROR_OUT_OF_MEMORY;
+
+    auto* data = static_cast<ModuleParentPrivate*>(parent->module_parent_private);
+    mutex_construct(&data->mutex);
+
+    return ERROR_NONE;
+}
+
+error_t module_parent_destruct(struct ModuleParent* parent) {
+    auto* data = static_cast<ModuleParentPrivate*>(parent->module_parent_private);
+    if (data == nullptr) return ERROR_NONE;
+
+    mutex_lock(&data->mutex);
+    if (!data->modules.empty()) {
+        mutex_unlock(&data->mutex);
+        return ERROR_INVALID_STATE;
+    }
+    mutex_unlock(&data->mutex);
+
+    mutex_destruct(&data->mutex);
+    delete data;
+    parent->module_parent_private = nullptr;
+    return ERROR_NONE;
+}
+
+#pragma endregion
+
+#pragma region module
+
+error_t module_set_parent(struct Module* module, struct ModuleParent* parent) {
+    if (module->internal.started) return ERROR_INVALID_STATE;
+    if (module->internal.parent == parent) return ERROR_NONE;
+
+    // Remove from old parent
+    if (module->internal.parent && module->internal.parent->module_parent_private) {
+        auto* old_data = static_cast<ModuleParentPrivate*>(module->internal.parent->module_parent_private);
+        mutex_lock(&old_data->mutex);
+        auto it = std::find(old_data->modules.begin(), old_data->modules.end(), module);
+        if (it != old_data->modules.end()) {
+            old_data->modules.erase(it);
+        }
+        mutex_unlock(&old_data->mutex);
+    }
+
+    module->internal.parent = parent;
+
+    // Add to new parent
+    if (parent && parent->module_parent_private) {
+        auto* new_data = static_cast<ModuleParentPrivate*>(parent->module_parent_private);
+        mutex_lock(&new_data->mutex);
+        new_data->modules.push_back(module);
+        mutex_unlock(&new_data->mutex);
+    }
+
+    return ERROR_NONE;
+}
+
+error_t module_start(struct Module* module) {
+    if (module->internal.started) return ERROR_NONE;
+    if (!module->internal.parent) return ERROR_INVALID_STATE;
+
+    error_t error = module->start();
+    module->internal.started = (error == ERROR_NONE);
+    return error;
+}
+
+bool module_is_started(struct Module* module) {
+    return module->internal.started;
+}
+
+error_t module_stop(struct Module* module) {
+    if (!module->internal.started) return ERROR_NONE;
+
+    error_t error = module->stop();
+    if (error != ERROR_NONE) {
+        return error;
+    }
+
+    module->internal.started = false;
+    return error;
+}
+
+#pragma endregion
+
+}
+