TactilityKernel improvements and more (#459)

TactilityKernel/Include/Tactility/Device.h

@@ -8,12 +8,13 @@
 extern "C" {
 #endif
 
-#include <Tactility/concurrent/Mutex.h>
-
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
+#include "Error.h"
+#include <Tactility/concurrent/Mutex.h>
+
 struct Driver;
 
 /** Enables discovering devices of the same type */
@@ -52,24 +53,26 @@ struct Device {
 /**
  * Initialize the properties of a device.
  *
- * @param[in] dev a device with all non-internal properties set
- * @return the result code (0 for success)
+ * @param[in] device a device with all non-internal properties set
+ * @retval ERROR_OUT_OF_MEMORY
+ * @retval ERROR_NONE
  */
-int device_construct(struct Device* device);
+error_t device_construct(struct Device* device);
 
 /**
  * Deinitialize the properties of a device.
  * This fails when a device is busy or has children.
  *
- * @param[in] dev
- * @return the result code (0 for success)
+ * @param[in] device
+ * @retval ERROR_INVALID_STATE
+ * @retval ERROR_NONE
  */
-int device_destruct(struct Device* device);
+error_t device_destruct(struct Device* device);
 
 /**
  * Indicates whether the device is in a state where its API is available
  *
- * @param[in] dev non-null device pointer
+ * @param[in] device non-null device pointer
  * @return true if the device is ready for use
  */
 static inline bool device_is_ready(const struct Device* device) {
@@ -83,9 +86,10 @@ static inline bool device_is_ready(const struct Device* device) {
  * - a bus (if any)
  *
  * @param[in] device non-null device pointer
- * @return 0 on success
+ * @retval ERROR_INVALID_STATE
+ * @retval ERROR_NONE
  */
-int device_add(struct Device* device);
+error_t device_add(struct Device* device);
 
 /**
  * Deregister a device. Remove it from all relevant systems:
@@ -94,26 +98,32 @@ int device_add(struct Device* device);
  * - a bus (if any)
  *
  * @param[in] device non-null device pointer
- * @return 0 on success
+ * @retval ERROR_INVALID_STATE
+ * @retval ERROR_NOT_FOUND
+ * @retval ERROR_NONE
  */
-int device_remove(struct Device* device);
+error_t device_remove(struct Device* device);
 
 /**
  * Attach the driver.
  *
  * @warning must call device_construct() and device_add() first
  * @param device
- * @return ERROR_INVALID_STATE or otherwise the value of the driver binding result (0 on success)
+ * @retval ERROR_INVALID_STATE
+ * @retval ERROR_RESOURCE when driver binding fails
+ * @retval ERROR_NONE
  */
-int device_start(struct Device* device);
+error_t device_start(struct Device* device);
 
 /**
  * Detach the driver.
  *
  * @param device
- * @return ERROR_INVALID_STATE or otherwise the value of the driver unbinding result (0 on success)
+ * @retval ERROR_INVALID_STATE
+ * @retval ERROR_RESOURCE when driver unbinding fails
+ * @retval ERROR_NONE
  */
-int device_stop(struct Device* device);
+error_t device_stop(struct Device* device);
 
 /**
  * Set or unset a parent.
@@ -147,7 +157,7 @@ static inline void device_lock(struct Device* device) {
     mutex_lock(&device->internal.mutex);
 }
 
-static inline int device_try_lock(struct Device* device) {
+static inline bool device_try_lock(struct Device* device) {
     return mutex_try_lock(&device->internal.mutex);
 }
 
@@ -156,7 +166,7 @@ static inline void device_unlock(struct Device* device) {
 }
 
 static inline const struct DeviceType* device_get_type(struct Device* device) {
-    return device->internal.driver ? device->internal.driver->device_type : NULL;
+    return device->internal.driver ? device->internal.driver->deviceType : NULL;
 }
 /**
  * Iterate through all the known devices
@@ -167,18 +177,18 @@ void for_each_device(void* callback_context, bool(*on_device)(struct Device* dev
 
 /**
  * Iterate through all the child devices of the specified device
- * @param callback_context the parameter to pass to the callback. NULL is valid.
+ * @param callbackContext the parameter to pass to the callback. NULL is valid.
  * @param on_device the function to call for each filtered device. return true to continue iterating or false to stop.
  */
-void for_each_device_child(struct Device* device, void* callback_context, bool(*on_device)(struct Device* device, void* context));
+void for_each_device_child(struct Device* device, void* callbackContext, bool(*on_device)(struct Device* device, void* context));
 
 /**
  * Iterate through all the known devices of a specific type
  * @param type the type to filter
- * @param callback_context the parameter to pass to the callback. NULL is valid.
+ * @param callbackContext the parameter to pass to the callback. NULL is valid.
  * @param on_device the function to call for each filtered device. return true to continue iterating or false to stop.
  */
-void for_each_device_of_type(const struct DeviceType* type, void* callback_context, bool(*on_device)(struct Device* device, void* context));
+void for_each_device_of_type(const struct DeviceType* type, void* callbackContext, bool(*on_device)(struct Device* device, void* context));
 
 #ifdef __cplusplus
 }

TactilityKernel/Include/Tactility/Driver.h

@@ -7,6 +7,7 @@ extern "C" {
 #endif
 
 #include <stdbool.h>
+#include "Error.h"
 
 struct Device;
 struct DeviceType;
@@ -17,13 +18,13 @@ struct Driver {
     /** Array of const char*, terminated by NULL */
     const char**compatible;
     /** Function to initialize the driver for a device */
-    int (*start_device)(struct Device* dev);
+    error_t (*startDevice)(struct Device* dev);
     /** Function to deinitialize the driver for a device */
-    int (*stop_device)(struct Device* dev);
+    error_t (*stopDevice)(struct Device* dev);
     /** Contains the driver's functions */
     const void* api;
     /** Which type of devices this driver creates (can be NULL) */
-    const struct DeviceType* device_type;
+    const struct DeviceType* deviceType;
     /** Internal data */
     struct {
         /** Contains private data */
@@ -31,20 +32,20 @@ struct Driver {
     } internal;
 };
 
-int driver_construct(struct Driver* driver);
+error_t driver_construct(struct Driver* driver);
 
-int driver_destruct(struct Driver* driver);
+error_t driver_destruct(struct Driver* driver);
 
-int driver_bind(struct Driver* driver, struct Device* device);
+error_t driver_bind(struct Driver* driver, struct Device* device);
 
-int driver_unbind(struct Driver* driver, struct Device* device);
+error_t driver_unbind(struct Driver* driver, struct Device* device);
 
 bool driver_is_compatible(struct Driver* driver, const char* compatible);
 
 struct Driver* driver_find_compatible(const char* compatible);
 
 static inline const struct DeviceType* driver_get_device_type(struct Driver* driver) {
-    return driver->device_type;
+    return driver->deviceType;
 }
 
 #ifdef __cplusplus

TactilityKernel/Include/Tactility/Error.h

@@ -2,9 +2,18 @@
 
 #pragma once
 
+// Avoid potential clash with bits/types/error_t.h
+#ifndef __error_t_defined
+typedef int error_t;
+#endif
+
+#define ERROR_NONE 0
 #define ERROR_UNDEFINED 1
 #define ERROR_INVALID_STATE 2
 #define ERROR_INVALID_ARGUMENT 3
 #define ERROR_MISSING_PARAMETER 4
 #define ERROR_NOT_FOUND 5
-
+#define ERROR_ISR_STATUS 6
+#define ERROR_RESOURCE 7 // A problem with a resource/dependency
+#define ERROR_TIMEOUT 8
+#define ERROR_OUT_OF_MEMORY 9

TactilityKernel/Include/Tactility/concurrent/Dispatcher.h

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+* Dispatcher is a thread-safe code execution queue.
+*/
+#pragma once
+
+#include <Tactility/Error.h>
+#include <Tactility/FreeRTOS/FreeRTOS.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void (*DispatcherCallback)(void* context);
+typedef void* DispatcherHandle_t;
+
+DispatcherHandle_t dispatcher_alloc(void);
+
+void dispatcher_free(DispatcherHandle_t dispatcher);
+
+/**
+ * Queue a function to be consumed elsewhere.
+ *
+ * @param[in] callbackContext the data to pass to the function upon execution
+ * @param[in] callback the function to execute elsewhere
+ * @param[in] timeout lock acquisition timeout
+ * @retval ERROR_TIMEOUT
+ * @retval ERROR_RESOURCE when failing to set event
+ * @retval ERROR_INVALID_STATE when the dispatcher is in the process of shutting down
+ * @retval ERROR_NONE
+ */
+error_t dispatcher_dispatch_timed(DispatcherHandle_t dispatcher, void* callbackContext, DispatcherCallback callback, TickType_t timeout);
+
+/**
+ * Queue a function to be consumed elsewhere.
+ *
+ * @param[in] callbackContext the data to pass to the function upon execution
+ * @param[in] callback the function to execute elsewhere
+ * @retval ERROR_RESOURCE when failing to set event
+ * @retval ERROR_TIMEOUT unlikely to occur unless there's an issue with the internal mutex
+ * @retval ERROR_INVALID_STATE when the dispatcher is in the process of shutting down
+ * @retval ERROR_NONE
+ */
+static inline error_t dispatcher_dispatch(DispatcherHandle_t dispatcher, void* callbackContext, DispatcherCallback callback) {
+    return dispatcher_dispatch_timed(dispatcher, callbackContext, callback, portMAX_DELAY);
+}
+
+/**
+ * Consume 1 or more dispatched functions (if any) until the queue is empty.
+ *
+ * @warning The timeout is only the wait time before consuming the message! It is not a limit to the total execution time when calling this method.
+ *
+ * @param[in] timeout the ticks to wait for a message
+ * @retval ERROR_TIMEOUT
+ * @retval ERROR_RESOURCE failed to wait for event
+ * @retval ERROR_INVALID_STATE when the dispatcher is in the process of shutting down
+ * @retval ERROR_NONE
+ */
+error_t dispatcher_consume_timed(DispatcherHandle_t dispatcher, TickType_t timeout);
+
+/**
+ * Consume 1 or more dispatched functions (if any) until the queue is empty.
+ *
+ * @warning The timeout is only the wait time before consuming the message! It is not a limit to the total execution time when calling this method.
+ *
+ * @retval ERROR_TIMEOUT unlikely to occur unless there's an issue with the internal mutex
+ * @retval ERROR_RESOURCE failed to wait for event
+ * @retval ERROR_INVALID_STATE when the dispatcher is in the process of shutting down
+ * @retval ERROR_NONE
+ */
+static inline error_t dispatcher_consume(DispatcherHandle_t dispatcher) {
+    return dispatcher_consume_timed(dispatcher, portMAX_DELAY);
+}
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/Tactility/concurrent/EventGroup.h

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <assert.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+#include <Tactility/Error.h>
+#include <Tactility/FreeRTOS/event_groups.h>
+
+static inline void event_group_construct(EventGroupHandle_t* eventGroup) {
+    assert(xPortInIsrContext() == pdFALSE);
+    *eventGroup = xEventGroupCreate();
+}
+
+static inline void event_group_destruct(EventGroupHandle_t* eventGroup) {
+    assert(xPortInIsrContext() == pdFALSE);
+    assert(*eventGroup != NULL);
+    vEventGroupDelete(*eventGroup);
+    *eventGroup = NULL;
+}
+
+/**
+ * Set the flags.
+ *
+ * @param[in] eventGroup the event group
+ * @param[in] flags the flags to set
+ * @retval ERROR_RESOURCE when setting failed
+ * @retval ERROR_NONE
+ */
+error_t event_group_set(EventGroupHandle_t eventGroup, uint32_t flags);
+
+/**
+ * Clear flags
+ *
+ * @param[in] eventGroup the event group
+ * @param[in] flags the flags to clear
+ * @retval ERROR_RESOURCE when clearing failed
+ * @retval ERROR_NONE
+ */
+error_t event_group_clear(EventGroupHandle_t eventGroup, uint32_t flags);
+
+/**
+ * @param[in] eventGroup the event group
+ * @return the bitset (always succeeds)
+ */
+uint32_t event_group_get(EventGroupHandle_t eventGroup);
+
+/**
+ * Wait for flags to be set
+ *
+ * @param[in] eventGroup the event group
+ * @param[in] inFlags the flags to await
+ * @param[in] awaitAll If true, await for all bits to be set. Otherwise, await for any.
+ * @param[in] clearOnExit If true, clears all the bits on exit, otherwise don't clear.
+ * @param[out] outFlags If set to non-NULL value, this will hold the resulting flags. Only set when return value is ERROR_NONE
+ * @param[in] timeout the maximum amount of ticks to wait for flags to be set
+ * @retval ERROR_ISR_STATUS when the function was called from an ISR context
+ * @retval ERROR_TIMEOUT
+ * @retval ERROR_RESOURCE when flags were triggered, but not in a way that was expected (e.g. waiting for all flags, but was only partially set)
+ * @retval ERROR_NONE
+ */
+error_t event_group_wait(
+    EventGroupHandle_t eventGroup,
+    uint32_t inFlags,
+    bool awaitAll,
+    bool clearOnExit,
+    uint32_t* outFlags,
+    TickType_t timeout
+);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/Tactility/concurrent/Mutex.h

@@ -12,6 +12,7 @@ extern "C" {
 
 struct Mutex {
     QueueHandle_t handle;
+    // TODO: Debugging functionality
 };
 
 inline static void mutex_construct(struct Mutex* mutex) {
@@ -27,18 +28,30 @@ inline static void mutex_destruct(struct Mutex* mutex) {
 }
 
 inline static void mutex_lock(struct Mutex* mutex) {
+    assert(xPortInIsrContext() != pdTRUE);
     xSemaphoreTake(mutex->handle, portMAX_DELAY);
 }
 
 inline static bool mutex_try_lock(struct Mutex* mutex) {
+    assert(xPortInIsrContext() != pdTRUE);
     return xSemaphoreTake(mutex->handle, 0) == pdTRUE;
 }
 
+inline static bool mutex_try_lock_timed(struct Mutex* mutex, TickType_t timeout) {
+    assert(xPortInIsrContext() != pdTRUE);
+    return xSemaphoreTake(mutex->handle, timeout) == pdTRUE;
+}
+
 inline static bool mutex_is_locked(struct Mutex* mutex) {
-    return xSemaphoreGetMutexHolder(mutex->handle) != NULL;
+    if (xPortInIsrContext() == pdTRUE) {
+        return xSemaphoreGetMutexHolderFromISR(mutex->handle) != NULL;
+    } else {
+        return xSemaphoreGetMutexHolder(mutex->handle) != NULL;
+    }
 }
 
 inline static void mutex_unlock(struct Mutex* mutex) {
+    assert(xPortInIsrContext() != pdTRUE);
     xSemaphoreGive(mutex->handle);
 }
 

TactilityKernel/Include/Tactility/concurrent/RecursiveMutex.h

@@ -26,18 +26,30 @@ inline static void recursive_mutex_destruct(struct RecursiveMutex* mutex) {
 }
 
 inline static void recursive_mutex_lock(struct RecursiveMutex* mutex) {
+    assert(xPortInIsrContext() != pdTRUE);
     xSemaphoreTakeRecursive(mutex->handle, portMAX_DELAY);
 }
 
 inline static bool recursive_mutex_is_locked(struct RecursiveMutex* mutex) {
-    return xSemaphoreGetMutexHolder(mutex->handle) != NULL;
+    if (xPortInIsrContext() == pdTRUE) {
+        return xSemaphoreGetMutexHolderFromISR(mutex->handle) != NULL;
+    } else {
+        return xSemaphoreGetMutexHolder(mutex->handle) != NULL;
+    }
 }
 
 inline static bool recursive_mutex_try_lock(struct RecursiveMutex* mutex) {
+    assert(xPortInIsrContext() != pdTRUE);
     return xSemaphoreTakeRecursive(mutex->handle, 0) == pdTRUE;
 }
 
+inline static bool recursive_mutex_try_lock_timed(struct RecursiveMutex* mutex, TickType_t timeout) {
+    assert(xPortInIsrContext() != pdTRUE);
+    return xSemaphoreTakeRecursive(mutex->handle, timeout) == pdTRUE;
+}
+
 inline static void recursive_mutex_unlock(struct RecursiveMutex* mutex) {
+    assert(xPortInIsrContext() != pdTRUE);
     xSemaphoreGiveRecursive(mutex->handle);
 }
 

TactilityKernel/Include/Tactility/drivers/Gpio.h

@@ -6,6 +6,8 @@
 extern "C" {
 #endif
 
+#include <stdbool.h>
+#include <stdint.h>
 #include <Tactility/Device.h>
 
 #define GPIO_OPTIONS_MASK 0x1f
@@ -34,57 +36,30 @@ typedef enum {
     GPIO__MAX,
 } GpioInterruptType;
 
-/**
- * @brief Provides a type to hold a GPIO pin index.
- *
- * This reduced-size type is sufficient to record a pin number,
- * e.g. from a devicetree GPIOS property.
- */
+/** The index of a GPIO pin on a GPIO Controller */
 typedef uint8_t gpio_pin_t;
 
-/**
- * @brief Identifies a set of pins associated with a port.
- *
- * The pin with index n is present in the set if and only if the bit
- * identified by (1U << n) is set.
- */
-typedef uint32_t gpio_pinset_t;
-
-/**
- * @brief Provides a type to hold GPIO devicetree flags.
- *
- * All GPIO flags that can be expressed in devicetree fit in the low 16
- * bits of the full flags field, so use a reduced-size type to record
- * that part of a GPIOS property.
- *
- * The lower 8 bits are used for standard flags. The upper 8 bits are reserved
- * for SoC specific flags.
- */
+/** Specifies the configuration flags for a GPIO pin (or set of pins) */
 typedef uint16_t gpio_flags_t;
 
-/**
- * @brief Container for GPIO pin information specified in dts files
- *
- * This type contains a pointer to a GPIO device, pin identifier for a pin
- * controlled by that device, and the subset of pin configuration
- * flags which may be given in devicetree.
- */
+/** A configuration for a single GPIO pin */
 struct GpioPinConfig {
     /** GPIO device controlling the pin */
     const struct Device* port;
     /** The pin's number on the device */
     gpio_pin_t pin;
     /** The pin's configuration flags as specified in devicetree */
-    gpio_flags_t dt_flags;
+    gpio_flags_t flags;
 };
 
 /**
  * Check if the pin is ready to be used.
- * @param pin_config the specifications of the pin
+ *
+ * @param pinConfig the specifications of the pin
  * @return true if the pin is ready to be used
  */
-static inline bool gpio_is_ready(const struct GpioPinConfig* pin_config) {
-    return device_is_ready(pin_config->port);
+static inline bool gpio_is_ready(const struct GpioPinConfig* pinConfig) {
+    return device_is_ready(pinConfig->port);
 }
 
 #ifdef __cplusplus

TactilityKernel/Include/Tactility/drivers/GpioController.h

@@ -7,22 +7,22 @@ extern "C" {
 #endif
 
 #include "Gpio.h"
-#include <stdbool.h>
+#include <Tactility/Error.h>
 
 struct GpioControllerApi {
-    bool (*set_level)(struct Device* device, gpio_pin_t pin, bool high);
-    bool (*get_level)(struct Device* device, gpio_pin_t pin, bool* high);
-    bool (*set_options)(struct Device* device, gpio_pin_t pin, gpio_flags_t options);
-    bool (*get_options)(struct Device* device, gpio_pin_t pin, gpio_flags_t* options);
+    error_t (*set_level)(struct Device* device, gpio_pin_t pin, bool high);
+    error_t (*get_level)(struct Device* device, gpio_pin_t pin, bool* high);
+    error_t (*set_options)(struct Device* device, gpio_pin_t pin, gpio_flags_t options);
+    error_t (*get_options)(struct Device* device, gpio_pin_t pin, gpio_flags_t* options);
 };
 
-bool gpio_controller_set_level(struct Device* device, gpio_pin_t pin, bool high);
-bool gpio_controller_get_level(struct Device* device, gpio_pin_t pin, bool* high);
-bool gpio_controller_set_options(struct Device* device, gpio_pin_t pin, gpio_flags_t options);
-bool gpio_controller_get_options(struct Device* device, gpio_pin_t pin, gpio_flags_t* options);
+error_t gpio_controller_set_level(struct Device* device, gpio_pin_t pin, bool high);
+error_t gpio_controller_get_level(struct Device* device, gpio_pin_t pin, bool* high);
+error_t gpio_controller_set_options(struct Device* device, gpio_pin_t pin, gpio_flags_t options);
+error_t gpio_controller_get_options(struct Device* device, gpio_pin_t pin, gpio_flags_t* options);
 
-inline bool gpio_set_options_config(struct Device* device, struct GpioPinConfig* config) {
-    return gpio_controller_set_options(device, config->pin, config->dt_flags);
+static inline error_t gpio_set_options_config(struct Device* device, const struct GpioPinConfig* config) {
+    return gpio_controller_set_options(device, config->pin, config->flags);
 }
 
 #ifdef __cplusplus

TactilityKernel/Include/Tactility/drivers/I2cController.h

@@ -6,22 +6,24 @@
 extern "C" {
 #endif
 
-#include "Gpio.h"
-#include <Tactility/FreeRTOS/FreeRTOS.h>
-#include <stdbool.h>
 #include <stdint.h>
 
+#include "Gpio.h"
+
+#include <Tactility/FreeRTOS/FreeRTOS.h>
+#include <Tactility/Error.h>
+
 struct I2cControllerApi {
-    bool (*read)(struct Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
-    bool (*write)(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
-    bool (*write_read)(struct Device* device, uint8_t address, const uint8_t* write_data, size_t write_data_size, uint8_t* read_data, size_t read_data_size, TickType_t timeout);
+    error_t (*read)(struct Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
+    error_t (*write)(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+    error_t (*write_read)(struct Device* device, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout);
 };
 
-bool i2c_controller_read(struct Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
+error_t i2c_controller_read(struct Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
 
-bool i2c_controller_write(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+error_t i2c_controller_write(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
 
-bool i2c_controller_write_read(struct Device* device, uint8_t address, const uint8_t* write_data, size_t write_data_size, uint8_t* read_data, size_t read_data_size, TickType_t timeout);
+error_t i2c_controller_write_read(struct Device* device, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout);
 
 extern const struct DeviceType I2C_CONTROLLER_TYPE;
 

TactilityKernel/Source/Device.cpp

@@ -44,17 +44,17 @@ extern "C" {
 
 #define get_device_data(device) static_cast<DeviceData*>(device->internal.data)
 
-int device_construct(Device* device) {
+error_t device_construct(Device* device) {
     device->internal.data = new(std::nothrow) DeviceData;
     if (device->internal.data == nullptr) {
-        return ENOMEM;
+        return ERROR_OUT_OF_MEMORY;
     }
     LOG_I(TAG, "construct %s", device->name);
     mutex_construct(&device->internal.mutex);
-    return 0;
+    return ERROR_NONE;
 }
 
-int device_destruct(Device* device) {
+error_t device_destruct(Device* device) {
     if (device->internal.state.started || device->internal.state.added) {
         return ERROR_INVALID_STATE;
     }
@@ -65,7 +65,7 @@ int device_destruct(Device* device) {
     mutex_destruct(&device->internal.mutex);
     delete get_device_data(device);
     device->internal.data = nullptr;
-    return 0;
+    return ERROR_NONE;
 }
 
 /** Add a child to the list of children */
@@ -87,7 +87,7 @@ static void device_remove_child(struct Device* device, struct Device* child) {
     device_unlock(device);
 }
 
-int device_add(Device* device) {
+error_t device_add(Device* device) {
     LOG_I(TAG, "add %s", device->name);
 
     // Already added
@@ -107,10 +107,10 @@ int device_add(Device* device) {
     }
 
     device->internal.state.added = true;
-    return 0;
+    return ERROR_NONE;
 }
 
-int device_remove(Device* device) {
+error_t device_remove(Device* device) {
     LOG_I(TAG, "remove %s", device->name);
 
     if (device->internal.state.started || !device->internal.state.added) {
@@ -133,7 +133,7 @@ int device_remove(Device* device) {
     ledger_unlock();
 
     device->internal.state.added = false;
-    return 0;
+    return ERROR_NONE;
 
 failed_ledger_lookup:
 
@@ -145,7 +145,7 @@ failed_ledger_lookup:
     return ERROR_NOT_FOUND;
 }
 
-int device_start(Device* device) {
+error_t device_start(Device* device) {
     if (!device->internal.state.added) {
         return ERROR_INVALID_STATE;
     }
@@ -156,33 +156,31 @@ int device_start(Device* device) {
 
     // Already started
     if (device->internal.state.started) {
-        return 0;
+        return ERROR_NONE;
     }
 
-    int result = driver_bind(device->internal.driver, device);
-    device->internal.state.started = (result == 0);
-    device->internal.state.start_result = result;
-    return result;
+    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;
 }
 
-int device_stop(struct Device* device) {
+error_t device_stop(struct Device* device) {
     if (!device->internal.state.added) {
         return ERROR_INVALID_STATE;
     }
 
-    // Not started
     if (!device->internal.state.started) {
-        return 0;
+        return ERROR_NONE;
     }
 
-    int result = driver_unbind(device->internal.driver, device);
-    if (result != 0) {
-        return result;
+    if (driver_unbind(device->internal.driver, device) != ERROR_NONE) {
+        return ERROR_RESOURCE;
     }
 
     device->internal.state.started = false;
     device->internal.state.start_result = 0;
-    return 0;
+    return ERROR_NONE;
 }
 
 void device_set_parent(Device* device, Device* parent) {
@@ -200,22 +198,22 @@ void for_each_device(void* callback_context, bool(*on_device)(Device* device, vo
     ledger_unlock();
 }
 
-void for_each_device_child(Device* device, void* callback_context, bool(*on_device)(struct Device* device, void* context)) {
+void for_each_device_child(Device* device, void* callbackContext, bool(*on_device)(struct Device* device, void* context)) {
     auto* data = get_device_data(device);
     for (auto* child_device : data->children) {
-        if (!on_device(child_device, callback_context)) {
+        if (!on_device(child_device, callbackContext)) {
             break;
         }
     }
 }
 
-void for_each_device_of_type(const DeviceType* type, void* callback_context, bool(*on_device)(Device* device, void* context)) {
+void for_each_device_of_type(const DeviceType* type, void* callbackContext, bool(*on_device)(Device* device, void* context)) {
     ledger_lock();
     for (auto* device : ledger.devices) {
         auto* driver = device->internal.driver;
         if (driver != nullptr) {
-            if (driver->device_type == type) {
-                if (!on_device(device, callback_context)) {
+            if (driver->deviceType == type) {
+                if (!on_device(device, callbackContext)) {
                     break;
                 }
             }

TactilityKernel/Source/Driver.cpp

@@ -15,6 +15,7 @@
 struct DriverInternalData {
     Mutex mutex { 0 };
     int use_count = 0;
+    bool destroying = false;
 
     DriverInternalData() {
         mutex_construct(&mutex);
@@ -64,7 +65,7 @@ static void driver_add(Driver* driver) {
     ledger.unlock();
 }
 
-static bool driver_remove(Driver* driver) {
+static error_t driver_remove(Driver* driver) {
     LOG_I(TAG, "remove %s", driver->name);
 
     ledger.lock();
@@ -72,35 +73,41 @@ static bool driver_remove(Driver* driver) {
     // check that there actually is a 3 in our vector
     if (iterator == ledger.drivers.end()) {
         ledger.unlock();
-        return false;
+        return ERROR_NOT_FOUND;
     }
     ledger.drivers.erase(iterator);
     ledger.unlock();
 
-    return true;
+    return ERROR_NONE;
 }
 
 extern "C" {
 
-int driver_construct(Driver* driver) {
+error_t driver_construct(Driver* driver) {
     driver->internal.data = new(std::nothrow) DriverInternalData;
     if (driver->internal.data == nullptr) {
-        return ENOMEM;
+        return ERROR_OUT_OF_MEMORY;
     }
     driver_add(driver);
-    return 0;
+    return ERROR_NONE;
 }
 
-int driver_destruct(Driver* driver) {
-    // Check if in use
-    if (driver_internal_data(driver)->use_count != 0) {
+error_t driver_destruct(Driver* driver) {
+    driver_lock(driver);
+    if (driver_internal_data(driver)->use_count != 0 || driver_internal_data(driver)->destroying) {
+        driver_unlock(driver);
         return ERROR_INVALID_STATE;
     }
+    driver_internal_data(driver)->destroying = true;
+    driver_unlock(driver);
+
+    if (driver_remove(driver) != ERROR_NONE) {
+        LOG_W(TAG, "Failed to remove driver from ledger: %s", driver->name);
+    }
 
-    driver_remove(driver);
     delete driver_internal_data(driver);
     driver->internal.data = nullptr;
-    return 0;
+    return ERROR_NONE;
 }
 
 bool driver_is_compatible(Driver* driver, const char* compatible) {
@@ -130,18 +137,18 @@ Driver* driver_find_compatible(const char* compatible) {
     return result;
 }
 
-int driver_bind(Driver* driver, Device* device) {
+error_t driver_bind(Driver* driver, Device* device) {
     driver_lock(driver);
 
-    int err = 0;
-    if (!device_is_added(device)) {
-        err = ERROR_INVALID_STATE;
+    error_t error = ERROR_NONE;
+    if (driver_internal_data(driver)->destroying || !device_is_added(device)) {
+        error = ERROR_INVALID_STATE;
         goto error;
     }
 
-    if (driver->start_device != nullptr) {
-        err = driver->start_device(device);
-        if (err != 0) {
+    if (driver->startDevice != nullptr) {
+        error = driver->startDevice(device);
+        if (error != ERROR_NONE) {
             goto error;
         }
     }
@@ -150,26 +157,26 @@ int driver_bind(Driver* driver, Device* device) {
     driver_unlock(driver);
 
     LOG_I(TAG, "bound %s to %s", driver->name, device->name);
-    return 0;
+    return ERROR_NONE;
 
 error:
 
     driver_unlock(driver);
-    return err;
+    return error;
 }
 
-int driver_unbind(Driver* driver, Device* device) {
+error_t driver_unbind(Driver* driver, Device* device) {
     driver_lock(driver);
 
-    int err = 0;
-    if (!device_is_added(device)) {
-        err = ERROR_INVALID_STATE;
+    error_t error = ERROR_NONE;
+    if (driver_internal_data(driver)->destroying || !device_is_added(device)) {
+        error = ERROR_INVALID_STATE;
         goto error;
     }
 
-    if (driver->stop_device != nullptr) {
-        err = driver->stop_device(device);
-        if (err != 0) {
+    if (driver->stopDevice != nullptr) {
+        error = driver->stopDevice(device);
+        if (error != ERROR_NONE) {
             goto error;
         }
     }
@@ -179,12 +186,12 @@ int driver_unbind(Driver* driver, Device* device) {
 
     LOG_I(TAG, "unbound %s to %s", driver->name, device->name);
 
-    return 0;
+    return ERROR_NONE;
 
 error:
 
     driver_unlock(driver);
-    return err;
+    return error;
 }
 
 } // extern "C"

TactilityKernel/Source/concurrent/Dispatcher.cpp

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <queue>
+
+#include <Tactility/concurrent/Dispatcher.h>
+
+#include "Tactility/Error.h"
+
+#include <Tactility/Log.h>
+#include <Tactility/concurrent/EventGroup.h>
+#include <Tactility/concurrent/Mutex.h>
+#include <atomic>
+
+#define TAG LOG_TAG("Dispatcher")
+
+static constexpr EventBits_t BACKPRESSURE_WARNING_COUNT = 100U;
+static constexpr EventBits_t WAIT_FLAG = 1U;
+
+struct QueuedItem {
+    DispatcherCallback callback;
+    void* context;
+};
+
+struct DispatcherData {
+    Mutex mutex = { 0 };
+    std::queue<QueuedItem> queue = {};
+    EventGroupHandle_t eventGroup = nullptr;
+    std::atomic<bool> shutdown{false}; // TODO: Use EventGroup
+
+    DispatcherData() {
+        event_group_construct(&eventGroup);
+        mutex_construct(&mutex);
+    }
+
+    ~DispatcherData() {
+        event_group_destruct(&eventGroup);
+        mutex_destruct(&mutex);
+    }
+};
+
+#define dispatcher_data(handle) static_cast<DispatcherData*>(handle)
+
+extern "C" {
+
+DispatcherHandle_t dispatcher_alloc(void) {
+    return new DispatcherData();
+}
+
+void dispatcher_free(DispatcherHandle_t dispatcher) {
+    auto* data = dispatcher_data(dispatcher);
+    data->shutdown.store(true, std::memory_order_release);
+    mutex_lock(&data->mutex);
+    mutex_unlock(&data->mutex);
+    delete data;
+}
+
+error_t dispatcher_dispatch_timed(DispatcherHandle_t dispatcher, void* callbackContext, DispatcherCallback callback, TickType_t timeout) {
+    auto* data = dispatcher_data(dispatcher);
+
+    // Mutate
+    if (!mutex_try_lock_timed(&data->mutex, timeout)) {
+#ifdef ESP_PLATFORM
+        LOG_E(TAG, "Mutex acquisition timeout");
+#endif
+        return ERROR_TIMEOUT;
+    }
+
+    if (data->shutdown.load(std::memory_order_acquire)) {
+        mutex_unlock(&data->mutex);
+        return ERROR_INVALID_STATE;
+    }
+
+    data->queue.push({
+        .callback = callback,
+        .context = callbackContext
+    });
+
+    if (data->queue.size() == BACKPRESSURE_WARNING_COUNT) {
+#ifdef ESP_PLATFORM
+        LOG_W(TAG, "Backpressure: You're not consuming fast enough (100 queued)");
+#endif
+    }
+
+    mutex_unlock(&data->mutex);
+
+    if (event_group_set(data->eventGroup, WAIT_FLAG) != ERROR_NONE) {
+#ifdef ESP_PLATFORM
+        LOG_E(TAG, "Failed to set flag");
+#endif
+        return ERROR_RESOURCE;
+    }
+
+    return ERROR_NONE;
+}
+
+error_t dispatcher_consume_timed(DispatcherHandle_t dispatcher, TickType_t timeout) {
+    auto* data = dispatcher_data(dispatcher);
+
+    // TODO: keep track of time and consider the timeout input as total timeout
+
+    // Wait for signal
+    error_t error = event_group_wait(data->eventGroup, WAIT_FLAG, false, true, nullptr, timeout);
+    if (error != ERROR_NONE) {
+        if (error == ERROR_TIMEOUT) {
+            return ERROR_TIMEOUT;
+        } else {
+            return ERROR_RESOURCE;
+        }
+    }
+
+    if (data->shutdown.load(std::memory_order_acquire)) {
+        return ERROR_INVALID_STATE;
+    }
+
+    // Mutate
+    bool processing = true;
+    do {
+        if (mutex_try_lock_timed(&data->mutex, 10)) {
+            if (!data->queue.empty()) {
+                // Make a copy, so it's thread-safe when we unlock
+                auto entry = data->queue.front();
+                data->queue.pop();
+                processing = !data->queue.empty();
+                // Don't keep lock as callback might be slow and we want to allow dispatch in the meanwhile
+                mutex_unlock(&data->mutex);
+                entry.callback(entry.context);
+            } else {
+                processing = false;
+                mutex_unlock(&data->mutex);
+            }
+        } else {
+#ifdef ESP_PLATFORM
+            LOG_W(TAG, "Mutex acquisition timeout");
+#endif
+        }
+
+    } while (processing && !data->shutdown.load(std::memory_order_acquire));
+
+    return ERROR_NONE;
+}
+
+}

TactilityKernel/Source/concurrent/EventGroup.cpp

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <Tactility/concurrent/EventGroup.h>
+#include <Tactility/Error.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+error_t event_group_set(EventGroupHandle_t eventGroup, uint32_t inFlags) {
+    if (xPortInIsrContext() == pdTRUE) {
+        BaseType_t yield = pdFALSE;
+        if (xEventGroupSetBitsFromISR(eventGroup, inFlags, &yield) == pdFAIL) {
+            return ERROR_RESOURCE;
+        }
+        portYIELD_FROM_ISR(yield);
+    } else {
+        xEventGroupSetBits(eventGroup, inFlags);
+    }
+    return ERROR_NONE;
+}
+
+error_t event_group_clear(EventGroupHandle_t eventGroup, uint32_t flags) {
+    if (xPortInIsrContext() == pdTRUE) {
+        if (xEventGroupClearBitsFromISR(eventGroup, flags) == pdFAIL) {
+            return ERROR_RESOURCE;
+        }
+        portYIELD_FROM_ISR(pdTRUE);
+    } else {
+        xEventGroupClearBits(eventGroup, flags);
+    }
+    return ERROR_NONE;
+}
+
+uint32_t event_group_get(EventGroupHandle_t eventGroup) {
+    if (xPortInIsrContext() == pdTRUE) {
+        return xEventGroupGetBitsFromISR(eventGroup);
+    } else {
+        return xEventGroupGetBits(eventGroup);
+    }
+}
+
+error_t event_group_wait(
+    EventGroupHandle_t eventGroup,
+    uint32_t inFlags,
+    bool awaitAll,
+    bool clearOnExit,
+    uint32_t* outFlags,
+    TickType_t timeout
+) {
+    if (xPortInIsrContext()) {
+        return ERROR_ISR_STATUS;
+    }
+
+    uint32_t result_flags = xEventGroupWaitBits(
+        eventGroup,
+        inFlags,
+        clearOnExit ? pdTRUE : pdFALSE,
+        awaitAll ? pdTRUE : pdFALSE,
+        timeout
+    );
+
+    auto invalid_flags = awaitAll
+        ? ((inFlags & result_flags) != inFlags) // await all
+        : ((inFlags & result_flags) == 0U); // await any
+
+    if (invalid_flags) {
+        const uint32_t matched = inFlags & result_flags;
+        if (matched == 0U) {
+            return ERROR_TIMEOUT;
+        }
+        return ERROR_RESOURCE;
+    }
+
+    if (outFlags != nullptr) {
+        *outFlags = result_flags;
+    }
+
+    return ERROR_NONE;
+}
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Source/drivers/GpioController.cpp

@@ -7,22 +7,22 @@
 
 extern "C" {
 
-bool gpio_controller_set_level(Device* device, gpio_pin_t pin, bool high) {
+error_t gpio_controller_set_level(Device* device, gpio_pin_t pin, bool high) {
     const auto* driver = device_get_driver(device);
     return GPIO_DRIVER_API(driver)->set_level(device, pin, high);
 }
 
-bool gpio_controller_get_level(Device* device, gpio_pin_t pin, bool* high) {
+error_t gpio_controller_get_level(Device* device, gpio_pin_t pin, bool* high) {
     const auto* driver = device_get_driver(device);
     return GPIO_DRIVER_API(driver)->get_level(device, pin, high);
 }
 
-bool gpio_controller_set_options(Device* device, gpio_pin_t pin, gpio_flags_t options) {
+error_t gpio_controller_set_options(Device* device, gpio_pin_t pin, gpio_flags_t options) {
     const auto* driver = device_get_driver(device);
     return GPIO_DRIVER_API(driver)->set_options(device, pin, options);
 }
 
-bool gpio_controller_get_options(Device* device, gpio_pin_t pin, gpio_flags_t* options) {
+error_t gpio_controller_get_options(Device* device, gpio_pin_t pin, gpio_flags_t* options) {
     const auto* driver = device_get_driver(device);
     return GPIO_DRIVER_API(driver)->get_options(device, pin, options);
 }

TactilityKernel/Source/drivers/I2cController.cpp

@@ -2,24 +2,25 @@
 
 #include <Tactility/drivers/I2cController.h>
 #include <Tactility/Driver.h>
+#include <Tactility/Error.h>
 
 #define I2C_DRIVER_API(driver) ((struct I2cControllerApi*)driver->api)
 
 extern "C" {
 
-bool i2c_controller_read(Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout) {
+error_t i2c_controller_read(Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout) {
     const auto* driver = device_get_driver(device);
     return I2C_DRIVER_API(driver)->read(device, address, data, dataSize, timeout);
 }
 
-bool i2c_controller_write(Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
+error_t i2c_controller_write(Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
     const auto* driver = device_get_driver(device);
     return I2C_DRIVER_API(driver)->write(device, address, data, dataSize, timeout);
 }
 
-bool i2c_controller_write_read(Device* device, uint8_t address, const uint8_t* write_data, size_t write_data_size, uint8_t* read_data, size_t read_data_size, TickType_t timeout) {
+error_t i2c_controller_write_read(Device* device, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout) {
     const auto* driver = device_get_driver(device);
-    return I2C_DRIVER_API(driver)->write_read(device, address, write_data, write_data_size, read_data, read_data_size, timeout);
+    return I2C_DRIVER_API(driver)->write_read(device, address, writeData, writeDataSize, readData, readDataSize, timeout);
 }
 
 const struct DeviceType I2C_CONTROLLER_TYPE { 0 };

TactilityKernel/Source/drivers/Root.cpp

@@ -8,10 +8,10 @@ extern "C" {
 Driver root_driver = {
     .name = "root",
     .compatible = (const char*[]) { "root", nullptr },
-    .start_device = nullptr,
-    .stop_device = nullptr,
+    .startDevice = nullptr,
+    .stopDevice = nullptr,
     .api = nullptr,
-    .device_type = nullptr,
+    .deviceType = nullptr,
     .internal = { 0 }
 };