From ee82d85875902acb63d5b3b8070218dac96ca233 Mon Sep 17 00:00:00 2001
From: Soren Soe <2106410+stsoe@users.noreply.github.com>
Date: Tue, 10 Sep 2024 13:03:58 -0700
Subject: [PATCH] Add xrt::runlist::state() to return runlist ERT command state
 (#8407)

* Add xrt::runlist::state() to return runlist ERT command state

The xrt::runlist::state() API mirrors xrt::run::state() and is the
preferred method for polling a runlist for completion.

Except for return value, the xrt::runlist::poll() API is functionally
the same, but is now deprecated.

Signed-off-by: Soren Soe <2106410+stsoe@users.noreply.github.com>

* Ensure runlist state reflects errors if any

The runlist may be composed of multiple chained commands. Upon runlist
completion, the state of the runlist must reflect errors (if any) in
any of the submitted chained commands.

Signed-off-by: Soren Soe <2106410+stsoe@users.noreply.github.com>

---------

Signed-off-by: Soren Soe <2106410+stsoe@users.noreply.github.com>
---
 .../core/common/api/xrt_kernel.cpp            | 46 ++++++++++++++++---
 .../core/include/experimental/xrt_kernel.h    | 18 ++++++++
 2 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/src/runtime_src/core/common/api/xrt_kernel.cpp b/src/runtime_src/core/common/api/xrt_kernel.cpp
index aede2ce13d1..c44028ed25d 100644
--- a/src/runtime_src/core/common/api/xrt_kernel.cpp
+++ b/src/runtime_src/core/common/api/xrt_kernel.cpp
@@ -758,7 +758,7 @@ class kernel_command : public xrt_core::command
   get_state() const
   {
     // For lazy state update the command must be polled. Polling
-    // is a no-op on platforms where command status is live.
+    // is a no-op on platforms where command state is live.
     m_hwqueue.poll(this);
     
     auto state = get_state_raw();
@@ -3037,16 +3037,23 @@ class runlist_impl
   // command has comleted (error or not), then in-order execution
   // guarantees that all prior command have completed (error or not).
   //
-  // This funtion returns 0 to indicate that last command is still
-  // running.  Any other return value implies completion.
-  int
+  // This funtion returns the ert command packet state of the last
+  // command or ERT_CMD_STATE_COMPLETED if no commands have been
+  // submitted.
+  ert_cmd_state
   poll_last_cmd() const
   {
+    // Treat empty runlist as completed
     if (m_submitted_cmds.empty())
-      return 1;
+      return ERT_CMD_STATE_COMPLETED;
 
     auto [cmd, pkt] = unpack(m_submitted_cmds.back());
-    return m_hwqueue.poll(cmd);
+
+    // For lazy state update the command must be polled. Polling
+    // is a no-op on platforms where command state is live.
+    m_hwqueue.poll(cmd);
+    
+    return static_cast<ert_cmd_state>(pkt->state);
   }
 
   // Wait for runlist to complete, then check each chained command
@@ -3248,7 +3255,7 @@ class runlist_impl
     if (m_state != state::running)
       return 1;
 
-    if (!poll_last_cmd())
+    if (poll_last_cmd() < ERT_CMD_STATE_COMPLETED)
       return 0;
 
     // All commands have completed.  Handle errors.
@@ -3256,6 +3263,24 @@ class runlist_impl
     return 1;
   }
 
+  ert_cmd_state
+  get_ert_state()
+  {
+    // Poll state of the last submitted chained command
+    if (auto state = poll_last_cmd(); state < ERT_CMD_STATE_COMPLETED)
+      return state;
+
+    // All chained commands have completed.  Handle errors in
+    // any of the submitted chained commands.
+    try {
+      wait_throw_on_error(std::chrono::milliseconds(0));
+      return ERT_CMD_STATE_COMPLETED;
+    }
+    catch (const xrt::runlist::command_error& err) {
+      return err.get_command_state();
+    }
+  }
+
   void
   reset()
   {
@@ -3955,6 +3980,13 @@ wait(const std::chrono::milliseconds& timeout) const
   return handle->wait_throw_on_error(timeout);
 }
 
+ert_cmd_state
+runlist::
+state() const
+{
+  return handle->get_ert_state();
+}
+
 int
 runlist::
 poll() const
diff --git a/src/runtime_src/core/include/experimental/xrt_kernel.h b/src/runtime_src/core/include/experimental/xrt_kernel.h
index 145723e19d1..fe08fe70cfc 100644
--- a/src/runtime_src/core/include/experimental/xrt_kernel.h
+++ b/src/runtime_src/core/include/experimental/xrt_kernel.h
@@ -189,6 +189,24 @@ class runlist : public detail::pimpl<runlist_impl>
   }
 
   /**
+   * state() - Check the current state of a runlist object
+   *
+   * @return
+   *  Current state of this run object.
+   *
+   * The state values are defined in ``include/ert.h``
+   * The state of an empty runlist is ERT_CMD_STATE_COMPLETED.
+   *
+   * This function is the preferred way to poll a runlist for
+   * for completion.
+   */
+  XRT_API_EXPORT
+  ert_cmd_state
+  state() const;
+
+  /**
+   * DEPRECATED, prefer `state()`.
+   *
    * Poll the runlist for completion.
    *
    * @return 0 if command list is still running, any other value