Adding stackful coroutine support + example.

Author: nicolasnoble

src/mips/psyqo/Makefile

@@ -10,6 +10,7 @@ $(wildcard ../../../third_party/EASTL/source/*.cpp) \
 ../common/crt0/memory-c.c \
 ../common/crt0/memory-s.s \
 ../common/hardware/flushcache.s \
+../common/psxlibc/ucontext.s \
 ../common/syscalls/printf.s \
 $(wildcard src/hardware/*.cpp) \
 $(wildcard src/*.cpp) \

src/mips/psyqo/coroutine.hh

@@ -29,6 +29,7 @@ SOFTWARE.
 #include <coroutine>
 #include <type_traits>
 
+#include "common/psxlibc/ucontext.h"
 #include "common/syscalls/syscalls.h"
 
 namespace psyqo {
@@ -208,4 +209,97 @@ struct Coroutine {
     }
 };
 
+class StackfulBase {
+  protected:
+    void initializeInternal(eastl::function<void()>&& func, void* ss_sp, unsigned ss_size);
+    void resume();
+    void yield();
+    [[nodiscard]] bool isAlive() const { return m_isAlive; }
+
+    StackfulBase() = default;
+    StackfulBase(const StackfulBase&) = delete;
+    StackfulBase& operator=(const StackfulBase&) = delete;
+
+  private:
+    static void trampoline(void* arg) {
+        StackfulBase* self = static_cast<StackfulBase*>(arg);
+        self->trampoline();
+    }
+    void trampoline();
+    ucontext_t m_coroutine;
+    ucontext_t m_return;
+    eastl::function<void()> m_func;
+    bool m_isAlive = false;
+};
+
+/**
+ * @brief Stackful coroutine class.
+ *
+ * @details This class provides a simple stackful coroutine implementation.
+ * It allows you to create coroutines that can yield and resume execution.
+ * While the Coroutine class above is a C++20 coroutine, it requires
+ * that all of the code being run are coroutines or awaitables all the way down.
+ * This class is a more traditional coroutine implementation that uses
+ * a separate stack for each coroutine, allowing it to yield and resume
+ * execution without requiring the entire call stack to be coroutine-aware.
+ * It is suitable for use in scenarios where you need to yield execution
+ * from legacy code without converting it to C++20 coroutines.
+ */
+template <unsigned StackSize = 0x10000>
+class Stackful : public StackfulBase {
+  public:
+    static constexpr unsigned c_stackSize = (StackSize + 7) & ~7;
+
+    Stackful() = default;
+    Stackful(const Stackful&) = delete;
+    Stackful& operator=(const Stackful&) = delete;
+
+    /**
+     * @brief Initialize the coroutine with a function and an argument.
+     *
+     * @param func Function to be executed by the coroutine.
+     * @param arg Argument to be passed to the function.
+     */
+    void initialize(eastl::function<void()>&& func) {
+        initializeInternal(eastl::move(func), m_stack.data, c_stackSize);
+    }
+
+    /**
+     * @brief Resume the coroutine.
+     *
+     * @details This will switch to the coroutine's context and execute it.
+     * If the coroutine is not alive, this function does nothing. This
+     * function should be called after the coroutine has been initialized,
+     * and it will return to the point where the coroutine was last yielded.
+     * It can only be called from the "main thread".
+     */
+    void resume() { StackfulBase::resume(); }
+
+    /**
+     * @brief Yield the coroutine.
+     *
+     * @details This will switch back to the main thread and save the
+     * coroutine's context. The coroutine can be resumed later using
+     * `resume()`. It can only be called from within the coroutine
+     * to yield execution.
+     */
+    void yield() { StackfulBase::yield(); }
+
+    /**
+     * @brief Check if the coroutine is currently alive.
+     * @details A coroutine is considered alive if it has been initialized
+     * and has not yet completed its execution. It becomes not alive
+     * when it returns from its function.
+     *
+     * @return true if the coroutine is alive, false otherwise.
+     */
+    [[nodiscard]] bool isAlive() const { return StackfulBase::isAlive(); }
+
+  private:
+    struct alignas(8) Stack {
+        uint8_t data[c_stackSize];
+    };
+    Stack m_stack;
+};
+
 }  // namespace psyqo

src/mips/psyqo/examples/coroutine-demo-3/Makefile

@@ -0,0 +1,12 @@
+TARGET = coroutine-demo-3
+TYPE = ps-exe
+
+SRCS = \
+coroutine-demo-3.cpp \
+
+ifeq ($(TEST),true)
+CPPFLAGS = -Werror
+endif
+CXXFLAGS = -std=c++20 -fcoroutines
+
+include ../../psyqo.mk

src/mips/psyqo/examples/coroutine-demo-3/coroutine-demo-3.cpp

@@ -0,0 +1,116 @@
+/*
+
+MIT License
+
+Copyright (c) 2025 PCSX-Redux authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+*/
+
+#include <EASTL/string.h>
+
+#include "common/syscalls/syscalls.h"
+#include "psyqo/application.hh"
+#include "psyqo/coroutine.hh"
+#include "psyqo/font.hh"
+#include "psyqo/gpu.hh"
+#include "psyqo/kernel.hh"
+#include "psyqo/scene.hh"
+#include "psyqo/xprintf.h"
+
+namespace {
+
+class CoroutineDemo3 final : public psyqo::Application {
+    void prepare() override;
+    void createScene() override;
+
+  public:
+    psyqo::Font<> m_font;
+};
+
+class CoroutineDemoScene final : public psyqo::Scene {
+    void frame() override;
+    void start(StartReason reason) override;
+    void coroutine();
+    psyqo::Stackful<65536> m_coroutine;
+    eastl::string m_text;
+};
+
+CoroutineDemo3 coroutineDemo3;
+CoroutineDemoScene coroutineDemoScene;
+
+}  // namespace
+
+void CoroutineDemo3::prepare() {
+    psyqo::GPU::Configuration config;
+    config.set(psyqo::GPU::Resolution::W320)
+        .set(psyqo::GPU::VideoMode::AUTO)
+        .set(psyqo::GPU::ColorMode::C15BITS)
+        .set(psyqo::GPU::Interlace::PROGRESSIVE);
+    gpu().initialize(config);
+}
+
+void CoroutineDemo3::createScene() {
+    m_font.uploadSystemFont(gpu());
+    pushScene(&coroutineDemoScene);
+}
+
+void CoroutineDemoScene::start(StartReason reason) {
+    psyqo::Kernel::assert(reason == StartReason::Create, "Wrong internal state");
+    m_coroutine.initialize([this]() { coroutine(); });
+    m_coroutine.resume();
+}
+
+void CoroutineDemoScene::coroutine() {
+    using namespace psyqo::timer_literals;
+    m_text = "Coroutine... sleeping for 2s";
+    gpu().armTimer(gpu().now() + 2_s, [this](uint32_t) {
+        m_text = "Coroutine... waking up";
+        m_coroutine.resume();
+    });
+    m_coroutine.yield();
+    m_text = "Waking up... sleeping for 1s";
+    gpu().armTimer(gpu().now() + 1_s, [this](uint32_t) {
+        m_text = "Waking up... sleeping for 5s this time";
+        m_coroutine.resume();
+    });
+    m_coroutine.yield();
+    m_text = "Waking up... sleeping again for 1s";
+    gpu().armTimer(gpu().now() + 1_s, [this](uint32_t) {
+        m_text = "Waking up... sleeping for 5s this time";
+        m_coroutine.resume();
+    });
+    m_coroutine.yield();
+    m_text = "Waking up... sleeping for 5s this time";
+    gpu().armTimer(gpu().now() + 5_s, [this](uint32_t) {
+        m_text = "All done.";
+        m_coroutine.resume();
+    });
+    m_coroutine.yield();
+}
+
+void CoroutineDemoScene::frame() {
+    psyqo::Color bg{{.r = 0, .g = 64, .b = 91}};
+    coroutineDemo3.gpu().clear(bg);
+    auto c = psyqo::Color{{.r = 255, .g = 255, .b = 255}};
+    coroutineDemo3.m_font.print(coroutineDemo3.gpu(), m_text, {{.x = 4, .y = 32}}, c);
+}
+
+int main() { return coroutineDemo3.run(); }

src/mips/psyqo/src/coroutine.cpp

@@ -0,0 +1,52 @@
+/*
+
+MIT License
+
+Copyright (c) 2025 PCSX-Redux authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+*/
+
+#include "psyqo/coroutine.hh"
+
+void psyqo::StackfulBase::initializeInternal(eastl::function<void()>&& func, void* ss_sp, unsigned ss_size) {
+    m_isAlive = true;
+    m_func = eastl::move(func);
+    getcontext(&m_coroutine);
+    m_coroutine.uc_stack.ss_sp = ss_sp;
+    m_coroutine.uc_stack.ss_size = ss_size;
+    m_coroutine.uc_link = &m_return;
+    makecontext(&m_coroutine, trampoline, this);
+}
+
+void psyqo::StackfulBase::trampoline() {
+    m_func();
+    m_isAlive = false;
+}
+
+void psyqo::StackfulBase::resume() {
+    if (!m_isAlive) return;
+    swapcontext(&m_return, &m_coroutine);
+}
+
+void psyqo::StackfulBase::yield() {
+    if (!m_isAlive) return;
+    swapcontext(&m_coroutine, &m_return);
+}