Merge pull request #18435 from jia200x/pr/bhp

sys/bhp_*: add initial support for generic Bottom Half Processor

sys/Kconfig

@@ -12,6 +12,7 @@ rsource "arduino/Kconfig"
 rsource "auto_init/Kconfig"
 rsource "base64/Kconfig"
 rsource "benchmark/Kconfig"
+rsource "bhp/Kconfig"
 rsource "bitfield/Kconfig"
 rsource "bloom/Kconfig"
 rsource "bus/Kconfig"

sys/Makefile

@@ -5,6 +5,9 @@ endif
 ifneq (,$(filter benchmark_udp,$(USEMODULE)))
   DIRS += test_utils/benchmark_udp
 endif
+ifneq (,$(filter bhp,$(USEMODULE)))
+  DIRS += bhp
+endif
 ifneq (,$(filter bluetil_%,$(USEMODULE)))
   DIRS += net/ble/bluetil
 endif

sys/Makefile.dep

@@ -962,6 +962,10 @@ ifneq (,$(filter ecc_%,$(USEMODULE)))
   USEMODULE += ecc
 endif
 
+ifneq (,$(filter bhp_%,$(USEMODULE)))
+  USEMODULE += bhp
+endif
+
 ifneq (,$(filter dbgpin,$(USEMODULE)))
   FEATURES_REQUIRED += periph_gpio
   FEATURES_REQUIRED += dbgpin

sys/Makefile.include

@@ -1,3 +1,7 @@
+ifneq (,$(filter bhp,$(USEMODULE)))
+  include $(RIOTBASE)/sys/bhp/Makefile.include
+endif
+
 ifneq (,$(filter gnrc_sixlowpan_frag_rb,$(USEMODULE)))
   USEMODULE_INCLUDES += $(RIOTBASE)/sys/net/gnrc/network_layer/sixlowpan/frag
 endif

sys/bhp/Kconfig

@@ -0,0 +1,25 @@
+# Copyright (c) 2022 HAW Hamburg
+#
+# This file is subject to the terms and conditions of the GNU Lesser
+# General Public License v2.1. See the file LICENSE in the top level
+# directory for more details.
+#
+
+menu "Bottom Half Processor"
+
+config HAVE_BHP_IRQ_HANDLER
+    bool
+    select MODULE_BHP
+    help
+        "Indicates that a module exposes an IRQ Handler to be offloaded to a
+         Bottom Half Processor mechanism."
+
+config MODULE_BHP
+    bool
+
+config MODULE_BHP_EVENT
+    bool "Enable event based Bottom Half Processor implementation"
+    depends on MODULE_EVENT
+    depends on MODULE_BHP
+
+endmenu

sys/bhp/Makefile

@@ -0,0 +1,3 @@
+SUBMODULES := 1
+
+include $(RIOTBASE)/Makefile.base

sys/bhp/Makefile.include

@@ -0,0 +1 @@
+PSEUDOMODULES += bhp_event

sys/bhp/event.c

@@ -0,0 +1,40 @@
+/*
+ * Copyright (C) 2022 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     sys_bhp
+ * @{
+ *
+ * @file
+ * @brief       Event based Bottom Half Processor implementation
+ *
+ * @author      José I. Alamos <jose.alamos@haw-hamburg.de>
+ *
+ * @}
+ */
+#include <stdio.h>
+#include "bhp/event.h"
+
+static void _event_handler(event_t *event)
+{
+    bhp_event_t *bhp_event = container_of(event, bhp_event_t, ev);
+    bhp_irq_handler(&bhp_event->bhp);
+}
+
+void bhp_event_init(bhp_event_t *bhp_ev, event_queue_t *evq, bhp_cb_t cb, void *ctx)
+{
+    bhp_set_cb(&bhp_ev->bhp, cb, ctx);
+    bhp_ev->evq = evq;
+    bhp_ev->ev.handler = _event_handler;
+}
+
+void bhp_event_isr_cb(void *bhp_event_ctx)
+{
+    bhp_event_t *bhp_event = bhp_event_ctx;
+    event_post(bhp_event->evq, &bhp_event->ev);
+}

sys/include/bhp.h

@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) 2022 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser General
+ * Public License v2.1. See the file LICENSE in the top level directory for more
+ * details.
+ */
+
+/**
+ * @defgroup     sys_bhp Bottom Half Processor
+ * @ingroup      sys
+
+ * @brief        Base implementation of Bottom Half Processor module for generic
+ *               IRQ offloading.
+ *
+ * This module provides a generic mechanism to schedule an offload request
+ * (Top Half) from interrupt context and run the IRQ handler in thread context.
+ * A Bottom Half Processor interface stores a pointer to the device IRQ handler
+ * and context, which allows device agnostic IRQ offloading.
+ *
+ * A user of this module can either use the Bottom Half Processor interface directly
+ * or use an existing implementation of a Bottom Half Processor (see
+ * @ref sys_bhp_event)
+ * @{
+ *
+ * @author       José I. Alamos <jose.alamos@haw-hamburg.de>
+ */
+
+#ifndef BHP_H
+#define BHP_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Forward declaration of the Bottom Half Processor descriptor
+ */
+typedef struct bhp bhp_t;
+
+/**
+ * @brief A Bottom Half Processor callback
+ *
+ * @param[in] arg   Context of the callback
+ */
+typedef void (*bhp_cb_t)(void *arg);
+
+/**
+ * @brief Bottom Half Processor descriptor
+ */
+struct bhp {
+    bhp_cb_t irq_handler;   /**< Bottom Half Processor IRQ handler */
+    void *ctx;              /**< Context of the IRQ handler */
+};
+
+/**
+ * @brief Call the IRQ handler associated to a Bottom Half Processor descriptor
+ *
+ * @note It is possible, although not recommended, to call this function on ISR. This
+ * can be done e.g when it is required to process the handler during ISR.
+ *
+ * @param[in] bhp   Pointer to the Bottom Half Processor descriptor
+ */
+static inline void bhp_irq_handler(bhp_t *bhp)
+{
+    bhp->irq_handler(bhp->ctx);
+}
+
+/**
+ * @brief Set the callback for a Bottom Half Processor
+ *
+ * This function should be called inside the init function of a device that requires
+ * ISR offloading.
+ *
+ * @param[in] bhp   Pointer to the Bottom Half Processor
+ * @param[in] cb    IRQ handler of the Bottom Half Processor
+ * @param[in] ctx   Context of the IRQ handler
+ */
+static inline void bhp_set_cb(bhp_t *bhp, bhp_cb_t cb, void *ctx)
+{
+    bhp->irq_handler = cb;
+    bhp->ctx = ctx;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BHP_H */
+/** @} */

sys/include/bhp/event.h

@@ -0,0 +1,62 @@
+/*
+ * Copyright (C) 2022 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser General
+ * Public License v2.1. See the file LICENSE in the top level directory for more
+ * details.
+ */
+
+/**
+ * @defgroup     sys_bhp_event Event based implementation of Bottom Half Processor
+ * @ingroup      sys_bhp
+
+ * @brief        Bottom Half Processor module for generic IRQ offloading.
+ * @{
+ *
+ * @author       José I. Alamos <jose.alamos@haw-hamburg.de>
+ */
+
+#ifndef BHP_EVENT_H
+#define BHP_EVENT_H
+
+#include "bhp.h"
+#include <event.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Event based Bottom Half Processor descriptor
+ */
+typedef struct {
+    bhp_t bhp;          /**< Bottom Half Processor descriptor */
+    event_queue_t *evq; /**< Pointer to the event queue */
+    event_t ev;         /**< Event holding the Bottom Half Processor handler */
+} bhp_event_t;
+
+/**
+ * @brief Init a Bottom Half Processor to be used with events
+ *
+ * @param[in] bhp_ev    The Event based Bottom Half Processor descriptor
+ * @param[in] evq       The target event queue to process the Bottom Half Processor
+ * @param[in] cb        Bottom Half Processor callback
+ * @param[in] ctx       Context of @p cb
+ */
+void bhp_event_init(bhp_event_t *bhp_ev, event_queue_t *evq, bhp_cb_t cb, void *ctx);
+
+/**
+ * @brief Event based Bottom Half Processor ISR callback
+ *        To be called from ISR in order to trigger the Bottom Half Processor.
+ *
+ * @param[in] bhp_event_ctx     Context (@ref bhp_event_t) of the event based
+ *                              Bottom Half Processor.
+ */
+void bhp_event_isr_cb(void *bhp_event_ctx);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* BHP_EVENT_H */
+/** @} */

tests/unittests/tests-bhp_event/Makefile

@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base

tests/unittests/tests-bhp_event/Makefile.include

@@ -0,0 +1,2 @@
+USEMODULE += bhp_event
+USEMODULE += event_thread

tests/unittests/tests-bhp_event/tests-bhp_event.c

@@ -0,0 +1,75 @@
+/*
+ * Copyright (C) 2022 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @{
+ *
+ * @file
+ */
+#include <errno.h>
+#include <stdlib.h>
+
+#include "bhp/event.h"
+#include "event.h"
+#include "event/thread.h"
+#include "embUnit.h"
+
+#include "unittests-constants.h"
+#include "tests-bhp_event.h"
+
+extern void auto_init_event_thread(void);
+
+static bhp_event_t bhp_event;
+static int canary;
+static int *ctx;
+
+static void bhp_handler(void *arg)
+{
+    TEST_ASSERT(arg == ctx);
+    canary = TEST_INT;
+}
+
+static void set_up(void)
+{
+    memset(&bhp_event, '\0', sizeof(bhp_event));
+    canary = 0;
+    bhp_event_init(&bhp_event, EVENT_PRIO_HIGHEST, bhp_handler, ctx);
+}
+
+static void test_bhp_event__init(void)
+{
+    TEST_ASSERT(bhp_event.evq == EVENT_PRIO_HIGHEST);
+    TEST_ASSERT(bhp_event.bhp.irq_handler == bhp_handler);
+    TEST_ASSERT(bhp_event.bhp.ctx == ctx);
+}
+
+static void test_bhp_event__cb(void)
+{
+    auto_init_event_thread();
+    TEST_ASSERT_EQUAL_INT(0, canary);
+    bhp_event_isr_cb(&bhp_event);
+    TEST_ASSERT_EQUAL_INT(TEST_INT, canary);
+}
+
+Test *tests_bhp_event_tests(void)
+{
+    EMB_UNIT_TESTFIXTURES(fixtures) {
+        new_TestFixture(test_bhp_event__init),
+        new_TestFixture(test_bhp_event__cb),
+    };
+
+    EMB_UNIT_TESTCALLER(bhp_event_tests, set_up, NULL, fixtures);
+
+    return (Test *)&bhp_event_tests;
+}
+
+void tests_bhp_event(void)
+{
+    TESTS_RUN(tests_bhp_event_tests());
+}
+/** @} */

tests/unittests/tests-bhp_event/tests-bhp_event.h

@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2022 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @addtogroup  unittests
+ * @{
+ *
+ * @file
+ * @brief       Unittests for the @ref bhp_event module
+ *
+ * @author      José I. Álamos <jose.alamos@haw-hamburg.de>
+ */
+#ifndef TESTS_BHP_EVENT_H
+#define TESTS_BHP_EVENT_H
+
+#include "embUnit.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   The entry point of this test suite.
+ */
+void tests_bhp_event(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* TESTS_BHP_EVENT_H */
+/** @} */