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;