From 824cc5a96f8a6f666a5c963897c8ab9076b48373 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Mon, 17 Aug 2026 15:20:57 +0200
Subject: kapi: add power management support to drivers

---
 kapi/kapi/devices.hpp        |  1 +
 kapi/kapi/devices/driver.hpp | 15 +++++++++++++++
 kapi/kapi/devices/power.hpp  | 38 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+)
 create mode 100644 kapi/kapi/devices/power.hpp

(limited to 'kapi')

diff --git a/kapi/kapi/devices.hpp b/kapi/kapi/devices.hpp
index b20e3546..0781357c 100644
--- a/kapi/kapi/devices.hpp
+++ b/kapi/kapi/devices.hpp
@@ -9,6 +9,7 @@
 #include <kapi/devices/driver_registry.hpp>  // IWYU pragma: export
 #include <kapi/devices/error.hpp>            // IWYU pragma: export
 #include <kapi/devices/facet_registry.hpp>   // IWYU pragma: export
+#include <kapi/devices/power.hpp>            // IWYU pragma: export
 #include <kapi/devices/resource.hpp>         // IWYU pragma: export
 
 #include <kstd/memory.hpp>
diff --git a/kapi/kapi/devices/driver.hpp b/kapi/kapi/devices/driver.hpp
index 20f66536..b46091fe 100644
--- a/kapi/kapi/devices/driver.hpp
+++ b/kapi/kapi/devices/driver.hpp
@@ -46,6 +46,21 @@ namespace kapi::devices
     //! @param device The device to release.
     virtual auto unbind(device & device) -> void = 0;
 
+    //! Suspend a device bound by this driver.
+    //!
+    //! This function will be invoked in in a depth-first manner, meaning any children of the bound device have already
+    //! been suspended. If suspension fails, the device must remain in, or be returned to, a non-suspended state by this
+    //! function.
+    //!
+    //! @param device The device to suspend.
+    //! @return Nothing on success, a error otherwise.
+    [[nodiscard]] virtual auto suspend(device & device) -> kstd::result<void>;
+
+    //! Resume a device bound by this driver.
+    //!
+    //! @param device The device to resume.
+    [[nodiscard]] virtual auto resume(device & device) -> kstd::result<void>;
+
     //! Retrieve this drivers implementation of a given capability facet.
     //!
     //! @return A pointer to this drivers implementation of the requested facet, nullptr if this driver does not
diff --git a/kapi/kapi/devices/power.hpp b/kapi/kapi/devices/power.hpp
new file mode 100644
index 00000000..44837a65
--- /dev/null
+++ b/kapi/kapi/devices/power.hpp
@@ -0,0 +1,38 @@
+#ifndef TEACHOS_KAPI_DEVICES_POWER_HPP
+#define TEACHOS_KAPI_DEVICES_POWER_HPP
+
+// IWYU pragma: private, include <kapi/devices.hpp>
+
+#include <kapi/devices/bus.hpp>
+
+#include <kstd/result.hpp>
+
+namespace kapi::devices
+{
+
+  //! @addtogroup kapi-devices-kernel-defined
+  //! @{
+
+  //! Suspend a device (sub-)tree rooted in a given bus.
+  //!
+  //! This function ensures a depth-first traversal and suspension of the given tree. In case suspension of a device
+  //! fails, a roll-back will be performed, resuming any previously suspended devices. Children will be suspended before
+  //! their parents are.
+  //!
+  //! @param root The root of the tree to suspend.
+  //! @return nothing on success, the first error to occur otherwise.
+  auto suspend_tree(bus & root) -> kstd::result<void>;
+
+  //! Resume a device (sub-)tree rooted in a given bus.
+  //!
+  //! This function resumes the tree in the reverse order of suspension performed by suspend_tree. On error, resumption
+  //! continues and error codes and messages are logged.
+  //!
+  //! @param root The root of the tree to resume.
+  auto resume_tree(bus & root) -> void;
+
+  //! @}
+
+}  // namespace kapi::devices
+
+#endif
\ No newline at end of file
-- 
cgit v1.2.3