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.