Remove old HAL components and refactored GPS-related code (#583)

- Added generic GPS/GNSS support with device detection, configuration, and persistent settings.
- Improved device and module lifecycle management.
- Added flexible filesystem locking support for displays and storage.
- Improved display-idle and keyboard backlight handling.
- Updated architecture, driver, module, testing, and licensing documentation.
- Removed old HAL device and related code.

TactilityKernel/include/tactility/device.h

@@ -24,6 +24,19 @@ struct DeviceType {
     const char* name;
 };
 
+typedef uint8_t device_flags_t;
+
+#ifndef BIT
+#define BIT(nr) (1u << (nr))
+#endif
+
+#define DEVICE_FLAG_DTS             BIT(0)  /* Instantiated from a dts file */
+#define DEVICE_FLAG_DYNAMIC         BIT(1)  /* 1 means dynamically allocated */
+
+#define DEVICE_FLAG_VIRTUAL         BIT(2)  /* No physical hardware */
+#define DEVICE_FLAG_REMOVABLE       BIT(3)  /* May disappear (USB, SDIO, etc.) */
+#define DEVICE_FLAG_HOTPLUG         BIT(4)  /* Supports hotplug */
+
 /** Represents a piece of hardware */
 struct Device {
     /** Device address. Can represent an index, a memory address, or some kind of offset */
@@ -38,6 +51,8 @@ struct Device {
     /** The parent device that this device belongs to. Can be NULL, but only the root device should have a NULL parent. */
     struct Device* parent;
 
+    device_flags_t flags;
+
     /**
      * Internal state managed by the kernel.
      * Device implementers should initialize this to NULL.
@@ -388,10 +403,19 @@ error_t device_get_first_by_type(const struct DeviceType* type, struct Device**
  * @param[in] type non-null device type pointer
  * @param[out] out_device receives the found device on success; untouched on failure
  * @retval ERROR_NOT_FOUND if no started device of that type exists
- * @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
+ * @retval ERROR_NONE if a started device of that type exists; must call device_put() exactly once afterwards.
  */
 error_t device_get_first_active_by_type(const struct DeviceType* type, struct Device** out_device);
 
+/**
+ * Check if there is an active device of the provided type.
+ *
+ * @param[in] type non-null device type pointer
+ * @retval ERROR_NOT_FOUND if no started device of that type exists
+ * @retval ERROR_NONE if a started device of that type exists
+ */
+bool device_has_active_by_type(const struct DeviceType* type);
+
 /**
  * Find the first device whose driver matches the given compatible string and atomically take a
  * reference on it. See device_get_by_name() for why this is preferred over

TactilityKernel/include/tactility/drivers/keyboard.h

@@ -37,6 +37,16 @@ struct KeyboardApi {
      * @retval ERROR_NONE when the operation was successful
      */
     error_t (*read_key)(struct Device* device, struct KeyboardKeyData* data);
+
+    /**
+     * @brief Returns the baclight if the keyboard has one.
+     * @warning Returns a referenced device. Must call device_put() afterwards.
+     * @param[in] device the keyboard device
+     * @param[out] backlight_device the output backlight device
+     * @retval ERROR_NONE when the backlight_device was set
+     * @retval ERROR_NOT_SUPPORTED when this device has no backlight
+     */
+    error_t (*get_backlight)(struct Device* device, struct Device** backlight_device);
 };
 
 /**
@@ -44,6 +54,17 @@ struct KeyboardApi {
  */
 error_t keyboard_read_key(struct Device* device, struct KeyboardKeyData* data);
 
+/**
+ * @brief Returns the backlight if the keyboard has one.
+ * @warning Returns a referenced device. Must call device_put() afterwards.
+ * @param[in] device the keyboard device
+ * @param[out] backlight_device the output backlight device
+ * @retval ERROR_NONE when the backlight_device was set
+ * @retval ERROR_NOT_SUPPORTED when this device has no backlight
+ */
+error_t keyboard_get_backlight(struct Device* device, struct Device** backlight_device);
+
+
 extern const struct DeviceType KEYBOARD_TYPE;
 
 #ifdef __cplusplus

TactilityKernel/include/tactility/filesystem/file_mutex.h

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/freertos/freertos.h>
+
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Set of lock/try_lock/unlock callbacks backing a filesystem mount's mutex.
+ * Any field left null is treated as a no-op by file_mutex_lock/try_lock/unlock.
+ */
+struct FileMutex {
+    void (*lock)();
+    bool (*try_lock)(uint32_t timeout);
+    void (*unlock)();
+};
+
+/**
+ * @brief Registers a mutex for a mount path (e.g. "/sdcard") and its descendants.
+ * @param[in] mutex callbacks to associate with the path; a copy is stored
+ * @param[in] path mount path this mutex serializes access to
+ * @note No-op if a mutex is already registered for this exact path.
+ */
+void file_mutex_register(const struct FileMutex* mutex, const char* path);
+
+/**
+ * @brief Looks up the mutex registered for path or one of its ancestor mount paths.
+ * @param[out] mutex receives the matching mutex, or an all-null (no-op) mutex if none matches
+ * @param[in] path file or directory path to look up
+ */
+void file_mutex_get(struct FileMutex* mutex, const char* path);
+
+/** @brief Locks mutex. No-op if mutex->lock is null. */
+void file_mutex_lock(const struct FileMutex* mutex);
+
+/**
+ * @brief Attempts to lock mutex within timeout.
+ * @return true if locked (or mutex->try_lock is null), false on timeout
+ */
+bool file_mutex_try_lock(const struct FileMutex* mutex, TickType_t timeout);
+
+/** @brief Unlocks mutex. No-op if mutex->unlock is null. */
+void file_mutex_unlock(const struct FileMutex* mutex);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/include/tactility/module.h

@@ -122,6 +122,22 @@ error_t module_stop(struct Module* module);
  */
 error_t module_construct_add_start(struct Module* module);
 
+/**
+ * @brief Tries to ensure the module is in a started state.
+ * Calls module_construct if needed, calls module_start if needed.
+ * @param module the module
+ * @return ERROR_NONE if module is in a started state
+ */
+error_t module_ensure_started(struct Module* module);
+
+/**
+ * @brief Tries to ensure the module is in a started state.
+ * Calls module_stop if needed, calls module_destruct if needed.
+ * @param module the module
+ * @return ERROR_NONE if module is in a destructed state
+ */
+error_t module_ensure_destructed(struct Module* module);
+
 /**
  * @brief Check if the module is started.
  * Can be used when module isn't constructed yet.

TactilityKernel/source/device.cpp

@@ -585,6 +585,20 @@ error_t device_get_first_active_by_type(const DeviceType* type, Device** out_dev
     return error;
 }
 
+bool device_has_active_by_type(const struct DeviceType* type) {
+    ledger_lock();
+    bool found = false;
+    for (auto* device : ledger.devices) {
+        auto* driver = device->internal->driver;
+        if (driver != nullptr && driver->device_type == type && device->internal->state.started) {
+            found = true;
+            break;
+        }
+    }
+    ledger_unlock();
+    return found;
+}
+
 error_t device_get_first_by_compatible(const char* compatible, Device** out_device) {
     ledger_lock();
     Device* found = nullptr;

TactilityKernel/source/drivers/keyboard.cpp

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 #include <tactility/drivers/keyboard.h>
+#include <tactility/error.h>
 #include <tactility/device.h>
 
 #define KEYBOARD_DRIVER_API(driver) ((struct KeyboardApi*)driver->api)
@@ -11,6 +12,16 @@ error_t keyboard_read_key(Device* device, KeyboardKeyData* data) {
     return KEYBOARD_DRIVER_API(driver)->read_key(device, data);
 }
 
+error_t keyboard_get_backlight(Device* device, Device** backlight_device) {
+    const auto* driver = device_get_driver(device);
+
+    if (KEYBOARD_DRIVER_API(driver)->get_backlight == nullptr) {
+        return ERROR_NOT_SUPPORTED;
+    }
+
+    return KEYBOARD_DRIVER_API(driver)->get_backlight(device, backlight_device);
+}
+
 const DeviceType KEYBOARD_TYPE {
     .name = "keyboard"
 };

TactilityKernel/source/filesystem/file_mutex.cpp

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <tactility/filesystem/file_mutex.h>
+
+#include <cstring>
+#include <string>
+#include <vector>
+
+static const FileMutex no_mutex = {
+    .lock = nullptr,
+    .try_lock = nullptr,
+    .unlock = nullptr,
+};
+
+struct FileMutexEntry {
+    std::string path;
+    FileMutex mutex;
+};
+
+static std::vector<FileMutexEntry> mutex_entries;
+
+extern "C" {
+
+void file_mutex_register(const FileMutex* mutex, const char* path) {
+    // Skip if entry for path exists
+    for (auto& entry : mutex_entries) {
+        if (entry.path == path) {
+            return;
+        }
+    }
+
+    // Store a copy of the entry
+    mutex_entries.push_back({
+        .path = path,
+        .mutex = *mutex
+    });
+}
+
+void file_mutex_get(FileMutex* mutex, const char* path) {
+    std::string path_string = path;
+    for (auto& entry : mutex_entries) {
+        // Match the mount path itself, or a descendant (e.g. "/sdcard" registered, "/sdcard/config.json" requested).
+        bool is_match = path_string == entry.path ||
+            (entry.path == "/" && !path_string.empty() && path_string[0] == '/') ||
+            (path_string.rfind(entry.path, 0) == 0 && path_string[entry.path.size()] == '/');
+        if (is_match) {
+            memcpy(mutex, &entry.mutex, sizeof(FileMutex));
+            return;
+        }
+    }
+
+    *mutex = no_mutex;
+}
+
+void file_mutex_lock(const FileMutex* mutex) {
+    if (mutex->lock) {
+        mutex->lock();
+    }
+}
+
+bool file_mutex_try_lock(const FileMutex* mutex, TickType_t timeout) {
+    if (mutex->try_lock) {
+        return mutex->try_lock(timeout);
+    }
+    return true;
+}
+
+void file_mutex_unlock(const FileMutex* mutex) {
+    if (mutex->unlock) {
+        mutex->unlock();
+    }
+}
+
+}

TactilityKernel/source/module.cpp

@@ -28,22 +28,39 @@ static ModuleLedger ledger;
 extern "C" {
 
 error_t module_construct(Module* module) {
+    if (module->internal != nullptr) {
+        LOG_E(TAG, "Module %s was already constructed", module->name);
+        return ERROR_INVALID_STATE;
+    }
     module->internal = new (std::nothrow) ModuleInternal();
     if (module->internal == nullptr) return ERROR_OUT_OF_MEMORY;
     return ERROR_NONE;
 }
 
 error_t module_destruct(Module* module) {
-    delete static_cast<ModuleInternal*>(module->internal);
+    if (module->internal == nullptr) {
+        LOG_E(TAG, "Module %s was already destructed", module->name);
+        return ERROR_INVALID_STATE;
+    }
+    delete module->internal;
     module->internal = nullptr;
     return ERROR_NONE;
 }
 
 error_t module_add(Module* module) {
     mutex_lock(&ledger.mutex);
-    ledger.modules.push_back(module);
+    bool exists = false;
+    for (auto* ledger_module : ledger.modules) {
+        if (ledger_module == module) {
+            exists = true;
+            break;
+        }
+    }
+    if (!exists) {
+        ledger.modules.push_back(module);
+    }
     mutex_unlock(&ledger.mutex);
-    return ERROR_NONE;
+    return exists ? ERROR_INVALID_STATE : ERROR_NONE;
 }
 
 error_t module_remove(Module* module) {
@@ -57,8 +74,8 @@ error_t module_start(Module* module) {
     LOG_I(TAG, "start %s", module->name);
 
     auto* internal = module->internal;
-    if (internal == nullptr) return ERROR_INVALID_STATE;
-    if (internal->started) return ERROR_NONE;
+    if (internal == nullptr) { return ERROR_INVALID_STATE; }
+    if (internal->started) { return ERROR_NONE; }
 
     if (module->start != nullptr) {
         auto error = module->start();
@@ -90,8 +107,8 @@ error_t module_stop(Module* module) {
     LOG_I(TAG, "stop %s", module->name);
 
     auto* internal = module->internal;
-    if (internal == nullptr) return ERROR_INVALID_STATE;
-    if (!internal->started) return ERROR_NONE;
+    if (internal == nullptr) { return ERROR_INVALID_STATE; }
+    if (!internal->started) { return ERROR_NONE; }
 
     if (module->drivers != nullptr && internal->drivers_ready) {
         size_t count = 0;
@@ -117,12 +134,41 @@ error_t module_stop(Module* module) {
 
 error_t module_construct_add_start(Module* module) {
     error_t error = module_construct(module);
-    if (error != ERROR_NONE) return error;
+    if (error != ERROR_NONE) { return error; }
     error = module_add(module);
-    if (error != ERROR_NONE) return error;
+    if (error != ERROR_NONE) { return error; }
     return module_start(module);
 }
 
+error_t module_ensure_started(Module* module) {
+    if (module->internal == nullptr) {
+        error_t result = module_construct(module);
+        if (result != ERROR_NONE) { return result; }
+    }
+
+    if (!module->internal->started) {
+        error_t result = module_start(module);
+        if (result != ERROR_NONE) { return result; }
+    }
+
+    return ERROR_NONE;
+}
+
+error_t module_ensure_destructed(Module* module) {
+    if (module->internal != nullptr) {
+        error_t result;
+        if (module->internal->started) {
+            result = module_stop(module);
+            if (result != ERROR_NONE) { return result; }
+        }
+
+        result = module_destruct(module);
+        if (result != ERROR_NONE) { return result; }
+    }
+
+    return ERROR_NONE;
+}
+
 bool module_resolve_symbol(Module* module, const char* symbol_name, uintptr_t* symbol_address) {
     if (!module_is_started(module)) return false;
     auto* symbol_ptr = module->symbols;