[processing] Implement Protothreads/Resumables using Fibers

Adds an lbuild option to replace the Protothread and (Nested)Resumable
implementation with a fiber one that is almost entirely backwards
compatible.

Author: salkinium

src/modm/processing/protothread/macros_fiber.hpp

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2011, 2018, Fabian Greif
+ * Copyright (c) 2012, 2014-2015, 2018, 2023, Niklas Hauser
+ * Copyright (c) 2017, Raphael Lehmann
+ *
+ * This file is part of the modm project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+// ----------------------------------------------------------------------------
+
+#ifndef MODM_PT_MACROS_FIBERS_HPP
+#define MODM_PT_MACROS_FIBERS_HPP
+
+#include <modm/architecture/utils.hpp>
+
+/// @ingroup modm_processing_protothread
+/// @{
+
+/**
+ * Declare start of protothread
+ *
+ * \warning	Use at start of the run() implementation!
+ * \hideinitializer
+ */
+#define PT_BEGIN()
+
+/**
+ * Stop protothread and end it
+ *
+ * \warning	Use at end of the run() implementation!
+ * \hideinitializer
+ */
+#define PT_END() \
+	return false;
+
+/// Yield protothread till next call to its run().
+/// \hideinitializer
+#define PT_YIELD() \
+	modm::fiber::yield()
+
+/// Cause protothread to wait **while** given condition is true.
+/// \hideinitializer
+#define PT_WAIT_WHILE(...) \
+	while(__VA_ARGS__) { PT_YIELD(); }
+
+/// Cause protothread to wait **until** given condition is true.
+/// \hideinitializer
+#define PT_WAIT_UNTIL(...) \
+	PT_WAIT_WHILE(!(__VA_ARGS__))
+
+/// Cause protothread to wait until given child protothread completes.
+/// \hideinitializer
+#define PT_WAIT_THREAD(...) \
+	PT_WAIT_WHILE((__VA_ARGS__).run())
+
+/// Restart and spawn given child protothread and wait until it completes.
+/// \hideinitializer
+#define PT_SPAWN(...) \
+	PT_WAIT_THREAD(__VA_ARGS__);
+
+
+/**
+ * Calls a given resumable function and returns
+ * whether it completed successfully or not.
+ * \hideinitializer
+ */
+#define PT_CALL(...) \
+	__VA_ARGS__
+
+/**
+ * Reset protothread to start from the beginning
+ *
+ * In the next executing cycle the protothread will restart its execution at
+ * its PT_BEGIN.
+ * \hideinitializer
+ */
+#define PT_RESTART() \
+	return true;
+
+/// Stop and exit from protothread.
+/// \hideinitializer
+#define PT_EXIT() \
+	return false;
+
+/// @}
+
+#endif // MODM_PT_MACROS_FIBERS_HPP

src/modm/processing/protothread/module.lb

@@ -17,9 +17,22 @@ def init(module):
 
 def prepare(module, options):
     module.depends(":architecture")
+    module.add_option(
+        BooleanOption(
+            name="use_fiber",
+            default=False,
+            description="Implement via Fibers",
+            dependencies=lambda v: ":processing:fiber" if v else None))
+
     return True
 
 def build(env):
     env.outbasepath = "modm/src/modm/processing/protothread"
-    env.copy(".")
+    if env["use_fiber"]:
+        env.copy("macros_fiber.hpp", "macros.hpp")
+        env.copy("protothread_fiber.hpp", "protothread.hpp")
+    else:
+        env.copy("macros.hpp")
+        env.copy("protothread.hpp")
+    env.copy("semaphore.hpp")
     env.copy("../protothread.hpp")

src/modm/processing/protothread/module.md

@@ -74,3 +74,58 @@ while (true) {
     light.run();
 }
 ```
+
+
+## Using Fibers
+
+Protothreads can be implemented using stackful fibers by setting the `use_fiber`
+option, which replaces the preprocessor macros and C++ implementations of this
+and the `modm:processing:resumable` module with a fiber version.
+
+Specifically, the `PT_*` and `RF_*` macros are now forwarding their arguments
+unmodified and instead relying on `modm::fiber::yield()` for context switching:
+
+```cpp
+#define PT_YIELD() modm::fiber::yield()
+#define PT_WAIT_WHILE(cond) while(cond) { modm::fiber::yield(); }
+#define PT_CALL(func) func
+```
+
+The `modm::pt::Protothread` class is implemented using `modm::Fiber<>` with the
+default stack size `MODM_PROTOTHREAD_STACK_SIZE`. It automatically runs the two
+virtual methods `bool run()` and `bool update()` if they are defined in the
+protothread class.
+
+There should be no modification of the existing code necessary with the
+exception that you must replace the main loop calling all protothreads with the
+fiber scheduler:
+
+```cpp
+int main()
+{
+    /*
+    while(true)
+    {
+        protothread1.update();
+        protothread2.update();
+    }
+    */
+    modm::fiber::Scheduler::run();
+    return 0;
+}
+```
+
+
+### Restrictions
+
+If the default stack size is too low, you can set `MODM_PROTOTHREAD_STACK_SIZE`
+to a higher value, however, this will apply to *all* protothreads, consuming a
+lot more memory. Instead, we recommend refactoring the protothread into a fiber
+function.
+
+All functions and macros work as expected, except for the  `Protothread::stop()`
+function, which not implementable using fibers. It is left unimplemented,
+so that you may define it with the behavior most suitable to your use case.
+
+See the `modm:processing:resumable` module for additional restrictions when
+calling resumable functions from a protothread.

src/modm/processing/protothread/protothread_fiber.hpp

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2023, Niklas Hauser
+ *
+ * This file is part of the modm project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+// ----------------------------------------------------------------------------
+
+#pragma once
+
+#include "macros.hpp"
+#include <modm/processing/fiber.hpp>
+
+/// @ingroup modm_processing_protothread
+#define MODM_PROTOTHREAD_IS_FIBER
+
+#ifndef MODM_PROTOTHREAD_STACK_SIZE
+/// @ingroup modm_processing_protothread
+#define MODM_PROTOTHREAD_STACK_SIZE ::modm::fiber::StackSizeDefault
+#endif
+
+namespace modm::pt
+{
+
+/// @ingroup modm_processing_protothread
+class Protothread : public modm::Fiber< MODM_PROTOTHREAD_STACK_SIZE >
+{
+public:
+	Protothread(modm::fiber::Start start=modm::fiber::Start::Now)
+	:	Fiber([this](){ while(update()) modm::fiber::yield(); }, start)
+	{}
+
+	void restart() { this->start(); }
+	void stop();
+	// isRunning() is implemented in fiber::Task
+
+	// The run() function name was never enforced by the Protothread interface
+	virtual bool run() { return false; };
+	// Instead update() was often chosen to align it more with other parts of
+	// modm that use an update() function to update their state periodically.
+	// Therefore we cover both here to not have to change too much code.
+	virtual bool update() { return run(); };
+};
+
+}

src/modm/processing/resumable.hpp

@@ -14,4 +14,3 @@
 // ----------------------------------------------------------------------------
 
 #include "resumable/resumable.hpp"
-#include "resumable/nested_resumable.hpp"

src/modm/processing/resumable/macros_fiber.hpp

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2023, Niklas Hauser
+ *
+ * This file is part of the modm project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+// ----------------------------------------------------------------------------
+
+#ifndef MODM_RF_MACROS_FIBER_HPP
+#define MODM_RF_MACROS_FIBER_HPP
+
+#include <modm/processing/fiber.hpp>
+
+/// @ingroup modm_processing_resumable
+/// @{
+
+/// Declare start of resumable function with index.
+/// @warning Use at start of the `resumable()` implementation!
+#define RF_BEGIN(...)
+
+
+/**
+ * End the resumable function and return a result.
+ *
+ * @warning	Use at end of the `resumable()` implementation only!
+ * @hideinitializer
+ */
+#define RF_END_RETURN(...) \
+	return __VA_ARGS__
+
+/**
+ * End the resumable function. You can use this to return `void`, or if the result does not matter.
+ *
+ * @warning	Use at end of the `resumable()` implementation only!
+ * @hideinitializer
+ */
+#define RF_END() \
+	return
+
+/**
+ * End the resumable function by calling another resumable function and returning its result.
+ *
+ * @warning	Use at end of the `resumable()` implementation only!
+ * @hideinitializer
+ */
+#define RF_END_RETURN_CALL(...) \
+	return __VA_ARGS__
+
+/// Yield resumable function until next invocation.
+/// @hideinitializer
+#define RF_YIELD() \
+	modm::fiber::yield()
+
+/// Cause resumable function to wait until given child protothread completes.
+/// @hideinitializer
+#define RF_WAIT_THREAD(...) \
+	RF_WAIT_WHILE((__VA_ARGS__).run())
+
+/// Cause resumable function to wait **while** given `condition` is true.
+/// @hideinitializer
+#define RF_WAIT_WHILE(...) \
+	while(__VA_ARGS__) { RF_YIELD(); }
+
+/// Cause resumable function to wait **until** given `condition` is true.
+/// @hideinitializer
+#define RF_WAIT_UNTIL(...) \
+	RF_WAIT_WHILE(!(__VA_ARGS__))
+
+/// Calls a resumable function and returns its result.
+/// @hideinitializer
+#define RF_CALL(...) \
+	__VA_ARGS__
+
+/**
+ * Calls a resumable function, busy-waits and returns its result.
+ *
+ * @hideinitializer
+ */
+#define RF_CALL_BLOCKING(...) \
+	__VA_ARGS__
+
+/// Exits a resumable function and returns another resumable function's result.
+/// @hideinitializer
+#define RF_RETURN_CALL(...) \
+	return __VA_ARGS__
+
+/// Stop and exit from resumable function with an optional result.
+/// @hideinitializer
+#define RF_RETURN(...) \
+	return __VA_ARGS__
+
+/// @}
+
+#endif // MODM_RF_MACROS_FIBER_HPP

src/modm/processing/resumable/module.lb

@@ -29,9 +29,14 @@ def prepare(module, options):
 
 def build(env):
     env.outbasepath = "modm/src/modm/processing/resumable"
-    env.copy(".", ignore=env.ignore_files("*.md", "*.in"))
+    if env.get(":processing:protothread:use_fiber", False):
+        env.copy("macros_fiber.hpp", "macros.hpp")
+        env.copy("resumable_fiber.hpp", "resumable.hpp")
+    else:
+        env.copy("macros.hpp")
+        env.copy("resumable.hpp")
+        env.template("nested_resumable.hpp.in")
     env.copy("../resumable.hpp")
-    env.template("nested_resumable.hpp.in")
 
 
 # ============================ Option Descriptions ============================