kapi: add power management support to drivers

3 files changed, 54 insertions, 0 deletions

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