New kernel drivers and device implementation updates (#561)

- Added modular device support and devicetree bindings for ILI9341, ILI9488, CST816S, XPT2046, and GPIO button input, updating several board configurations for display/touch/backlight/keyboard/battery.
- Added a setting to control deprecated HAL usage (device property + Kconfig).

TactilityKernel/CMakeLists.txt

@@ -16,5 +16,6 @@ endif ()
 tactility_add_module(TactilityKernel
     SRCS ${SOURCE_FILES}
     INCLUDE_DIRS include/
+    PRIV_INCLUDE_DIRS private/
     REQUIRES ${REQUIRES_LIST}
 )

TactilityKernel/include/tactility/device.h

@@ -60,7 +60,8 @@ error_t device_construct(struct Device* device);
  * This fails when a device is busy or has children.
  *
  * @param[in,out] device non-null device pointer
- * @retval ERROR_INVALID_STATE if the device is busy or has children
+ * @retval ERROR_INVALID_STATE if the device is started, added, or has children
+ * @retval ERROR_RESOURCE_BUSY if the device has outstanding device_get() references
  * @retval ERROR_NONE on success
  */
 error_t device_destruct(struct Device* device);
@@ -92,6 +93,9 @@ error_t device_remove(struct Device* device);
  * Attach the driver.
  *
  * @warning must call device_construct() and device_add() first
+ * @warning the driver's start_device callback must not call device_lock()/device_get()/
+ *          device_start()/device_stop() on this same device - device_start() holds this
+ *          device's lock for its entire body, so doing so would deadlock.
  * @param[in,out] device non-null device pointer
  * @retval ERROR_INVALID_STATE if the device is already started or not added
  * @retval ERROR_RESOURCE when driver binding fails
@@ -102,8 +106,12 @@ error_t device_start(struct Device* device);
 /**
  * Detach the driver.
  *
+ * @warning the driver's stop_device callback must not call device_lock()/device_get()/
+ *          device_start()/device_stop() on this same device - device_stop() holds this
+ *          device's lock for its entire body, so doing so would deadlock.
  * @param[in,out] device non-null device pointer
  * @retval ERROR_INVALID_STATE if the device is not started
+ * @retval ERROR_RESOURCE_BUSY if the device has outstanding device_get() references
  * @retval ERROR_RESOURCE when driver unbinding fails
  * @retval ERROR_NONE on success
  */
@@ -226,6 +234,41 @@ bool device_try_lock(struct Device* device, TickType_t timeout);
  */
 void device_unlock(struct Device* device);
 
+/**
+ * Indicates whether device_construct() has been called and device_destruct() has not
+ * subsequently been called (or has been followed by another device_construct()).
+ *
+ * @param[in] device non-null device pointer
+ * @return true if the device is currently constructed
+ */
+bool device_is_constructed(const struct Device* device);
+
+/**
+ * Take a reference on a device, guaranteeing its driver data remains valid until a matching
+ * device_put(). Named after the Linux kernel's get_device()/put_device(). Intended to bracket
+ * a single hardware operation (one API call or a short sequence of them), not to be held across
+ * a blocking wait or unrelated later work - device_stop() fails with ERROR_RESOURCE_BUSY while
+ * any reference is outstanding.
+ *
+ * @param[in,out] device non-null device pointer, already known to be valid (e.g. a static
+ *                devicetree pointer, or one captured earlier under a lock) - device_get() does
+ *                not itself protect against a dangling/freed Device*. For a fresh lookup that
+ *                might race a concurrent teardown of a dynamically-allocated Device, use one of
+ *                the device_get_*() lookup functions below instead.
+ * @retval ERROR_INVALID_STATE if the device is not started (or has been destructed)
+ * @retval ERROR_NONE on success; caller must call device_put(device) exactly once
+ */
+error_t device_get(struct Device* device);
+
+/**
+ * Release a reference previously taken with a successful device_get() (or a successful
+ * device_get_by_name()/device_get_first_by_type()/device_get_first_active_by_type()/
+ * device_get_first_by_compatible()).
+ *
+ * @param[in,out] device non-null device pointer previously passed to a successful device_get() call
+ */
+void device_put(struct Device* device);
+
 /**
  * Get the type of a device.
  *
@@ -273,7 +316,7 @@ void device_for_each_of_type(const struct DeviceType* type, void* callback_conte
  * @param[in] type the type to check
  * @return true if a device of the specified type exists
  */
-bool device_exists_of_type(const struct DeviceType* type);
+bool device_exists_of_type(const struct DeviceType* type) ;
 
 /**
  * Find a device by its name.
@@ -281,7 +324,7 @@ bool device_exists_of_type(const struct DeviceType* type);
  * @param[in] name non-null device name to look up
  * @return the device pointer if found, or NULL if not found
  */
-struct Device* device_find_by_name(const char* name);
+struct Device* device_find_by_name(const char* name) __attribute__((deprecated("Use device_get_by_name() and device_put()")));
 
 /**
  * Find the first started device of the given type.
@@ -289,7 +332,7 @@ struct Device* device_find_by_name(const char* name);
  * @param[in] type non-null device type pointer
  * @return the first started device of the given type, or NULL if none found
  */
-struct Device* device_find_first_active_by_type(const struct DeviceType* type);
+struct Device* device_find_first_active_by_type(const struct DeviceType* type) __attribute__((deprecated("Use device_get_first_active_by_type() and device_put()")));
 
 /**
  * Find the first device of the given type.
@@ -297,7 +340,7 @@ struct Device* device_find_first_active_by_type(const struct DeviceType* type);
  * @param[in] type non-null device type pointer
  * @return the first device of the given type, or NULL if none found
  */
-struct Device* device_find_first_by_type(const struct DeviceType* type);
+struct Device* device_find_first_by_type(const struct DeviceType* type) __attribute__((deprecated("Use device_get_first_by_type() and device_put()")));
 
 /**
  * Find the first device whose driver matches the given compatible string.
@@ -305,7 +348,62 @@ struct Device* device_find_first_by_type(const struct DeviceType* type);
  * @param[in] compatible non-null compatible string to match
  * @return the first matching device, or NULL if none found
  */
-struct Device* device_find_first_by_compatible(const char* compatible);
+struct Device* device_find_first_by_compatible(const char* compatible) __attribute__((deprecated("Use device_get_first_by_compatible() and device_put()")));
+
+/**
+ * Find a device by name and atomically take a reference on it (equivalent to a device_find_by_name()
+ * immediately followed by a successful device_get(), but race-free: the lookup and the reference
+ * are taken under the same lock, so a device that gets torn down concurrently either isn't found
+ * or is safely referenced - there is no gap where a caller could be handed a pointer that's about
+ * to become invalid). Prefer this over device_find_by_name() + device_get() for any device that
+ * might be dynamically constructed/destructed at runtime (e.g. a hot-pluggable child device),
+ * rather than a static devicetree-defined one.
+ *
+ * @param[in] name non-null device name to look up
+ * @param[out] out_device receives the found device on success; untouched on failure
+ * @retval ERROR_NOT_FOUND if no device with that name exists
+ * @retval ERROR_INVALID_STATE if found but not started (no reference taken)
+ * @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
+ */
+error_t device_get_by_name(const char* name, struct Device** out_device);
+
+/**
+ * Find the first device of the given type and atomically take a reference on it. See
+ * device_get_by_name() for why this is preferred over device_find_first_by_type() + device_get()
+ * for dynamically constructed/destructed devices.
+ *
+ * @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 device of that type exists
+ * @retval ERROR_INVALID_STATE if found but not started (no reference taken)
+ * @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
+ */
+error_t device_get_first_by_type(const struct DeviceType* type, struct Device** out_device);
+
+/**
+ * Find the first started device of the given type and atomically take a reference on it. See
+ * device_get_by_name() for why this is preferred over device_find_first_active_by_type() +
+ * device_get() for dynamically constructed/destructed devices.
+ *
+ * @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
+ */
+error_t device_get_first_active_by_type(const struct DeviceType* type, struct Device** out_device);
+
+/**
+ * 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
+ * device_find_first_by_compatible() + device_get() for dynamically constructed/destructed devices.
+ *
+ * @param[in] compatible non-null compatible string to match
+ * @param[out] out_device receives the found device on success; untouched on failure
+ * @retval ERROR_NOT_FOUND if no matching device exists
+ * @retval ERROR_INVALID_STATE if found but not started (no reference taken)
+ * @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
+ */
+error_t device_get_first_by_compatible(const char* compatible, struct Device** out_device);
 
 #ifdef __cplusplus
 }

TactilityKernel/include/tactility/device_listener.h

@@ -0,0 +1,31 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct Device;
+
+enum DeviceEvent {
+    DEVICE_EVENT_STARTED,
+    DEVICE_EVENT_STOPPED,
+};
+
+typedef void (*DeviceListenerCallback)(
+    struct Device *dev,
+    enum DeviceEvent event,
+    void* context
+);
+
+struct DeviceEventListener {
+    DeviceListenerCallback callback;
+    void* callback_context;
+};
+
+void device_listener_add(DeviceListenerCallback* callback, void* context);
+
+void device_listener_remove(DeviceListenerCallback* callback);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/include/tactility/error.h

@@ -25,6 +25,7 @@ typedef int error_t;
 #define ERROR_NOT_ALLOWED 11
 #define ERROR_BUFFER_OVERFLOW 12
 #define ERROR_OUT_OF_RANGE 13
+#define ERROR_RESOURCE_BUSY 14 // Rejected: device/driver has outstanding references and cannot be stopped/destructed yet
 
 /** Convert an error_t to a human-readable text. Useful for logging. */
 const char* error_to_string(error_t error);

TactilityKernel/private/tactility/device_listener_internal.h

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <tactility/device_listener.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Internal to TactilityKernel: invoked by device lifecycle code (device_start/device_stop) to
+// notify all registered listeners of a device state transition. Not part of the public API -
+// external code only sees device_listener_add()/device_listener_remove().
+void device_listener_notify(struct Device* dev, enum DeviceEvent event);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/source/device.cpp

@@ -2,32 +2,53 @@
 
 #include <tactility/driver.h>
 #include <tactility/device.h>
+#include <tactility/device_listener_internal.h>
 #include <tactility/error.h>
 #include <tactility/log.h>
+#include <tactility/check.h>
+#include <tactility/concurrent/recursive_mutex.h>
 
 #include <ranges>
 #include <cassert>
 #include <cstring>
-#include <sys/errno.h>
 #include <vector>
 
 #define TAG "device"
 
 struct DeviceInternal {
     /** Address of the API exposed by the device instance. */
-    struct Driver* driver = nullptr;
+    Driver* driver = nullptr;
     /** The driver data for this device (e.g. a mutex) */
     void* driver_data = nullptr;
-    /** The mutex for device operations */
-    struct Mutex mutex {};
+    // The mutex for device operations. Recursive: some drivers (e.g. battery_sense.cpp)
+    // legitimately call device_add()/device_start() on a CHILD device from within their own
+    // start_device - device_add_child() then locks the PARENT (this same device) again on the
+    // same thread. A plain Mutex would deadlock here.
+    // NOTE: device_start()/device_stop() do NOT hold this across the driver's
+    // start_device/stop_device callback (see state.starting/state.stopping below) - that callback
+    // can add/remove child devices, which takes ledger_lock, and lookup helpers
+    // (device_get_by_name() etc.) take ledger_lock then this mutex via device_get(). Holding both
+    // at once in opposite orders would ABBA-deadlock against those lookups.
+    struct RecursiveMutex mutex {};
     /** The device state */
     struct {
         int start_result = 0;
         bool started : 1 = false;
         bool added : 1 = false;
+        // Set while driver_bind()/driver_unbind() runs, with `mutex` released. Blocks concurrent
+        // device_start()/device_stop() calls from racing the same transition; state.stopping is
+        // also checked by device_get() so no new ref can be acquired while a stop is in flight.
+        bool starting : 1 = false;
+        bool stopping : 1 = false;
     } state;
     /** Attached child devices */
     std::vector<Device*> children {};
+    // Outstanding device_get() holders. Guarded by `mutex`. device_get() refuses new refs once
+    // state.stopping is set, and device_stop() refuses to set state.stopping while this is > 0 -
+    // together that guarantees ref_count > 0 implies state.started == true, so by the time
+    // device_remove()/device_destruct() run (both already require !started), this is always
+    // already 0.
+    int32_t ref_count = 0;
 };
 
 struct DeviceLedger {
@@ -55,8 +76,8 @@ extern "C" {
 #define ledger_lock() mutex_lock(&ledger.mutex)
 #define ledger_unlock() mutex_unlock(&ledger.mutex)
 
-#define lock_internal(internal) mutex_lock(&internal->mutex)
-#define unlock_internal(internal) mutex_unlock(&internal->mutex)
+#define lock_internal(internal) recursive_mutex_lock(&internal->mutex)
+#define unlock_internal(internal) recursive_mutex_unlock(&internal->mutex)
 
 error_t device_construct(Device* device) {
     device->internal = new(std::nothrow) DeviceInternal;
@@ -64,7 +85,7 @@ error_t device_construct(Device* device) {
         return ERROR_OUT_OF_MEMORY;
     }
     LOG_D(TAG, "construct %s", device->name);
-    mutex_construct(&device->internal->mutex);
+    recursive_mutex_construct(&device->internal->mutex);
     return ERROR_NONE;
 }
 
@@ -81,17 +102,24 @@ error_t device_destruct(Device* device) {
         unlock_internal(device->internal);
         return ERROR_INVALID_STATE;
     }
+    // Callers are expected to sequence teardown correctly (device_stop() already refuses to
+    // clear `started` while ref_count > 0, so by the time !started holds above, ref_count is
+    // already 0) - this is a cheap defense-in-depth check, not a substitute for that discipline.
+    if (internal->ref_count > 0) {
+        unlock_internal(device->internal);
+        return ERROR_RESOURCE_BUSY;
+    }
     LOG_D(TAG, "destruct %s", device->name);
 
     device->internal = nullptr;
-    mutex_unlock(&internal->mutex);
+    recursive_mutex_unlock(&internal->mutex);
     delete internal;
 
     return ERROR_NONE;
 }
 
 /** Add a child to the list of children */
-static void device_add_child(struct Device* device, struct Device* child) {
+static void device_add_child(Device* device, Device* child) {
     device_lock(device);
     check(device->internal->state.added);
     device->internal->children.push_back(child);
@@ -99,7 +127,7 @@ static void device_add_child(struct Device* device, struct Device* child) {
 }
 
 /** Remove a child from the list of children */
-static void device_remove_child(struct Device* device, struct Device* child) {
+static void device_remove_child(Device* device, Device* child) {
     device_lock(device);
     const auto iterator = std::ranges::find(device->internal->children, child);
     if (iterator != device->internal->children.end()) {
@@ -168,46 +196,99 @@ failed_ledger_lookup:
 
 error_t device_start(Device* device) {
     LOG_I(TAG, "start %s", device->name);
-    if (!device->internal->state.added) {
-        return ERROR_INVALID_STATE;
-    }
+    auto* internal = device->internal;
+    lock_internal(internal);
 
-    if (device->internal->driver == nullptr) {
+    if (!internal->state.added || internal->driver == nullptr) {
+        unlock_internal(internal);
         return ERROR_INVALID_STATE;
     }
 
     // Already started
-    if (device->internal->state.started) {
+    if (internal->state.started) {
+        unlock_internal(internal);
         return ERROR_NONE;
     }
 
-    error_t bind_error = driver_bind(device->internal->driver, device);
-    device->internal->state.started = (bind_error == ERROR_NONE);
-    device->internal->state.start_result = bind_error;
-    return bind_error == ERROR_NONE ? ERROR_NONE : ERROR_RESOURCE;
-}
-
-error_t device_stop(struct Device* device) {
-    LOG_I(TAG, "stop %s", device->name);
-    if (!device->internal->state.added) {
-        return ERROR_INVALID_STATE;
+    // Already starting on another thread
+    if (internal->state.starting) {
+        unlock_internal(internal);
+        return ERROR_RESOURCE_BUSY;
     }
+    internal->state.starting = true;
+    unlock_internal(internal);
 
-    if (!device->internal->state.started) {
-        return ERROR_NONE;
-    }
+    // driver_bind() runs the driver's start_device callback, which may add/start child devices
+    // (device_add() takes ledger_lock) - `mutex` must stay released across this call. See the
+    // comment on `mutex` above.
+    error_t bind_error = driver_bind(internal->driver, device);
 
-    if (driver_unbind(device->internal->driver, device) != ERROR_NONE) {
+    lock_internal(internal);
+    internal->state.starting = false;
+    internal->state.started = (bind_error == ERROR_NONE);
+    internal->state.start_result = bind_error;
+    unlock_internal(internal);
+
+    if (bind_error != ERROR_NONE) {
         return ERROR_RESOURCE;
     }
 
-    device->internal->state.started = false;
-    device->internal->state.start_result = 0;
+    device_listener_notify(device, DEVICE_EVENT_STARTED);
+
     return ERROR_NONE;
 }
 
-error_t device_construct_add(struct Device* device, const char* compatible) {
-    struct Driver* driver = driver_find_compatible(compatible);
+error_t device_stop(Device* device) {
+    LOG_I(TAG, "stop %s", device->name);
+    auto* internal = device->internal;
+    lock_internal(internal);
+
+    if (!internal->state.added) {
+        unlock_internal(internal);
+        return ERROR_INVALID_STATE;
+    }
+
+    if (!internal->state.started) {
+        unlock_internal(internal);
+        return ERROR_NONE;
+    }
+
+    if (internal->ref_count > 0) {
+        unlock_internal(internal);
+        return ERROR_RESOURCE_BUSY;
+    }
+
+    // Already stopping on another thread
+    if (internal->state.stopping) {
+        unlock_internal(internal);
+        return ERROR_RESOURCE_BUSY;
+    }
+    internal->state.stopping = true;
+    unlock_internal(internal);
+
+    // driver_unbind() runs the driver's stop_device callback, which may remove/destruct child
+    // devices (device_remove() takes ledger_lock) - `mutex` must stay released across this call,
+    // same reasoning as device_start(). state.stopping keeps device_get() from handing out a new
+    // ref while ref_count is meant to stay at 0 during the unbind.
+    error_t unbind_error = driver_unbind(internal->driver, device);
+
+    lock_internal(internal);
+    internal->state.stopping = false;
+    if (unbind_error != ERROR_NONE) {
+        unlock_internal(internal);
+        return ERROR_RESOURCE;
+    }
+    internal->state.started = false;
+    internal->state.start_result = 0;
+    unlock_internal(internal);
+
+    device_listener_notify(device, DEVICE_EVENT_STOPPED);
+
+    return ERROR_NONE;
+}
+
+error_t device_construct_add(Device* device, const char* compatible) {
+    Driver* driver = driver_find_compatible(compatible);
     if (driver == nullptr) {
         LOG_E(TAG, "Can't find driver '%s' for device '%s'", compatible, device->name);
         return ERROR_RESOURCE;
@@ -235,7 +316,7 @@ error_t device_construct_add(struct Device* device, const char* compatible) {
     return error;
 }
 
-error_t device_construct_add_start(struct Device* device, const char* compatible) {
+error_t device_construct_add_start(Device* device, const char* compatible) {
     error_t error = device_construct_add(device, compatible);
     if (error != ERROR_NONE) {
         goto on_construct_add_error;
@@ -261,52 +342,76 @@ void device_set_parent(Device* device, Device* parent) {
     device->parent = parent;
 }
 
-Device* device_get_parent(struct Device* device) {
+Device* device_get_parent(Device* device) {
     return device->parent;
 }
 
-void device_set_driver(struct Device* device, struct Driver* driver) {
+void device_set_driver(Device* device, Driver* driver) {
     device->internal->driver = driver;
 }
 
-struct Driver* device_get_driver(struct Device* device) {
+Driver* device_get_driver(Device* device) {
     return device->internal->driver;
 }
 
-bool device_is_ready(const struct Device* device) {
+bool device_is_ready(const Device* device) {
     return device->internal->state.started;
 }
 
-bool device_is_compatible(const struct Device* device, const char* compatible) {
+bool device_is_compatible(const Device* device, const char* compatible) {
     if (device->internal->driver == nullptr) return false;
     return driver_is_compatible(device->internal->driver, compatible);
 }
 
-void device_set_driver_data(struct Device* device, void* driver_data) {
+void device_set_driver_data(Device* device, void* driver_data) {
     device->internal->driver_data = driver_data;
 }
 
-void* device_get_driver_data(struct Device* device) {
+void* device_get_driver_data(Device* device) {
     return device->internal->driver_data;
 }
 
-bool device_is_added(const struct Device* device) {
+bool device_is_added(const Device* device) {
     return device->internal->state.added;
 }
 
-void device_lock(struct Device* device) {
-    mutex_lock(&device->internal->mutex);
+void device_lock(Device* device) {
+    recursive_mutex_lock(&device->internal->mutex);
 }
 
-bool device_try_lock(struct Device* device, TickType_t timeout) {
-    return mutex_try_lock(&device->internal->mutex, timeout);
+bool device_try_lock(Device* device, TickType_t timeout) {
+    return recursive_mutex_try_lock(&device->internal->mutex, timeout);
 }
 
-void device_unlock(struct Device* device) {
-    mutex_unlock(&device->internal->mutex);
+void device_unlock(Device* device) {
+    recursive_mutex_unlock(&device->internal->mutex);
 }
 
-const struct DeviceType* device_get_type(struct Device* device) {
+bool device_is_constructed(const Device* device) {
+    return device->internal != nullptr;
+}
+
+error_t device_get(Device* device) {
+    auto* internal = device->internal;
+    lock_internal(internal);
+    if (!internal->state.started || internal->state.stopping) {
+        unlock_internal(internal);
+        return ERROR_INVALID_STATE;
+    }
+    internal->ref_count++;
+    unlock_internal(internal);
+    return ERROR_NONE;
+}
+
+void device_put(Device* device) {
+    auto* internal = device->internal;
+    lock_internal(internal);
+    check(internal->ref_count > 0);
+    internal->ref_count--;
+    unlock_internal(internal);
+}
+
+const DeviceType* device_get_type(Device* device) {
     return device->internal->driver ? device->internal->driver->device_type : NULL;
 }
 
@@ -320,7 +425,7 @@ void device_for_each(void* callback_context, bool(*on_device)(Device* device, vo
     ledger_unlock();
 }
 
-void device_for_each_child(Device* device, void* callbackContext, bool(*on_device)(struct Device* device, void* context)) {
+void device_for_each_child(Device* device, void* callbackContext, bool(*on_device)(Device* device, void* context)) {
     for (auto* child_device : device->internal->children) {
         if (!on_device(child_device, callbackContext)) {
             break;
@@ -409,4 +514,96 @@ Device* device_find_first_by_compatible(const char* compatible) {
     return ctx.found;
 }
 
+error_t device_get_by_name(const char* name, Device** out_device) {
+    ledger_lock();
+    Device* found = nullptr;
+    for (auto* device : ledger.devices) {
+        if (device->name != nullptr && std::strcmp(device->name, name) == 0) {
+            found = device;
+            break;
+        }
+    }
+    if (found == nullptr) {
+        ledger_unlock();
+        return ERROR_NOT_FOUND;
+    }
+    // device_get() takes internal->mutex while still holding ledger_lock here on purpose: it
+    // blocks device_remove() (which needs ledger_lock to erase `found`) for the span between
+    // finding the device and taking a ref on it, so `found` can't be torn down and freed out from
+    // under us in that window. This is the reverse lock order from device_start()/device_stop(),
+    // which release internal->mutex before touching ledger_lock - see the comment on
+    // DeviceInternal::mutex for why that asymmetry is deadlock-free.
+    error_t error = device_get(found);
+    ledger_unlock();
+    if (error == ERROR_NONE) {
+        *out_device = found;
+    }
+    return error;
+}
+
+error_t device_get_first_by_type(const DeviceType* type, Device** out_device) {
+    ledger_lock();
+    Device* found = nullptr;
+    for (auto* device : ledger.devices) {
+        auto* driver = device->internal->driver;
+        if (driver != nullptr && driver->device_type == type) {
+            found = device;
+            break;
+        }
+    }
+    if (found == nullptr) {
+        ledger_unlock();
+        return ERROR_NOT_FOUND;
+    }
+    error_t error = device_get(found);
+    ledger_unlock();
+    if (error == ERROR_NONE) {
+        *out_device = found;
+    }
+    return error;
+}
+
+error_t device_get_first_active_by_type(const DeviceType* type, Device** out_device) {
+    ledger_lock();
+    Device* found = nullptr;
+    for (auto* device : ledger.devices) {
+        auto* driver = device->internal->driver;
+        if (driver != nullptr && driver->device_type == type && device->internal->state.started) {
+            found = device;
+            break;
+        }
+    }
+    if (found == nullptr) {
+        ledger_unlock();
+        return ERROR_NOT_FOUND;
+    }
+    error_t error = device_get(found);
+    ledger_unlock();
+    if (error == ERROR_NONE) {
+        *out_device = found;
+    }
+    return error;
+}
+
+error_t device_get_first_by_compatible(const char* compatible, Device** out_device) {
+    ledger_lock();
+    Device* found = nullptr;
+    for (auto* device : ledger.devices) {
+        if (device_is_compatible(device, compatible)) {
+            found = device;
+            break;
+        }
+    }
+    if (found == nullptr) {
+        ledger_unlock();
+        return ERROR_NOT_FOUND;
+    }
+    error_t error = device_get(found);
+    ledger_unlock();
+    if (error == ERROR_NONE) {
+        *out_device = found;
+    }
+    return error;
+}
+
 } // extern "C"

TactilityKernel/source/device_listener.cpp

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <algorithm>
+#include <vector>
+
+#include <tactility/device_listener.h>
+#include <tactility/concurrent/mutex.h>
+#include <tactility/device_listener_internal.h>
+
+struct DeviceListenerLedger {
+    std::vector<DeviceEventListener> listeners;
+    Mutex mutex {};
+
+    DeviceListenerLedger() { mutex_construct(&mutex); }
+    ~DeviceListenerLedger() { mutex_destruct(&mutex); }
+
+    void lock() { mutex_lock(&mutex); }
+    void unlock() { mutex_unlock(&mutex); }
+};
+
+static DeviceListenerLedger ledger;
+
+extern "C" {
+
+void device_listener_add(DeviceListenerCallback* callback, void* context) {
+    ledger.lock();
+    ledger.listeners.push_back(DeviceEventListener{ *callback, context });
+    ledger.unlock();
+}
+
+void device_listener_remove(DeviceListenerCallback* callback) {
+    ledger.lock();
+    const auto iterator = std::ranges::find_if(ledger.listeners, [callback](const DeviceEventListener& listener) {
+        return listener.callback == *callback;
+    });
+    if (iterator != ledger.listeners.end()) {
+        ledger.listeners.erase(iterator);
+    }
+    ledger.unlock();
+}
+
+void device_listener_notify(Device* dev, DeviceEvent event) {
+    // Copy the listener list under the lock, then invoke callbacks after unlocking: a listener
+    // calling device_listener_add/remove from within its own callback would otherwise deadlock
+    // against this same (non-recursive) mutex, and a slow listener would block every other
+    // thread's add/remove for the duration of this notification.
+    ledger.lock();
+    const std::vector<DeviceEventListener> listeners_copy = ledger.listeners;
+    ledger.unlock();
+
+    for (const auto& listener : listeners_copy) {
+        listener.callback(dev, event, listener.callback_context);
+    }
+}
+
+} // extern "C"

TactilityKernel/source/error.cpp

@@ -31,6 +31,8 @@ const char* error_to_string(error_t error) {
             return "not allowed";
         case ERROR_BUFFER_OVERFLOW:
             return "buffer overflow";
+        case ERROR_RESOURCE_BUSY:
+            return "resource busy";
         default:
             return "unknown";
     }