[Offload] Design for async error handling

This updates the spec to provide a way for async errors to be signaled
from, for example, kernels. The error is stored on the queue and can be
queried with `olGetQueueError`. In addition, if any other queues are
waiting on the error'd queue they will also enter the error state.

With this design, both `olSyncEvent` and `olSyncQueue` will now exit
early on error. More specifically, unless a kernel gets trapped in an
infinite loop, both sync functions will always return in a finite amount
of time.

Author: RossBrunton

offload/liboffload/API/Common.td

@@ -90,6 +90,7 @@ def ol_errc_t : Enum {
     Etor<"COMPILE_FAILURE", "jit compile failure while processing binary image">,
     Etor<"LINK_FAILURE", "linker failure while processing binary image">,
     Etor<"BACKEND_FAILURE", "the plugin backend is in an invalid or unsupported state">,
+    Etor<"QUEUE_ERROR", "the queue entered an error state">,
     Etor<"UNINITIALIZED", "not initialized">,
 
     // Handle related errors - only makes sense for liboffload

offload/liboffload/API/Event.td

@@ -33,11 +33,15 @@ def olDestroyEvent : Function {
 
 def olSyncEvent : Function {
     let desc = "Block the calling thread until the event is complete.";
-    let details = [];
+    let details = [
+      "If the queue or any dependencies encounter an error, this returns early and no work after the error will be complete."
+    ];
     let params = [
         Param<"ol_event_handle_t", "Event", "handle of the event", PARAM_IN>
     ];
-    let returns = [];
+    let returns = [
+      Return<"OL_ERRC_QUEUE_ERROR", ["The queue associated with this event or any of its dependencies encountered an error"]>,
+    ];
 }
 
 def ol_event_info_t : Enum {

offload/liboffload/API/Queue.td

@@ -33,18 +33,23 @@ def olDestroyQueue : Function {
 
 def olSyncQueue : Function {
     let desc = "Block the calling thread until the enqueued work on a queue is complete.";
-    let details = [];
+    let details = [
+      "If the queue or any dependencies encounter an error, this returns early and no work after the error will be complete."
+    ];
     let params = [
         Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>
     ];
-    let returns = [];
+    let returns = [
+      Return<"OL_ERRC_INVALID_QUEUE_ERROR", ["The queue or any of it's dependencies encountered an error"]>,
+    ];
 }
 
 def olWaitEvents : Function {
     let desc = "Make any future work submitted to this queue wait until the provided events are complete.";
     let details = [
       "All events in `Events` must complete before the queue is unblocked.",
       "The input events can be from any queue on any device provided by the same platform as `Queue`.",
+      "If `Event`'s queue is different from `Queue`, a dependency is created. If `Event`'s queue enters the error state, then Queue will also enter the error state.",
     ];
     let params = [
         Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>,
@@ -125,3 +130,21 @@ def olLaunchHostFunction : Function {
   ];
   let returns = [];
 }
+
+def olGetQueueError : Function {
+  let desc = "Gets the error from a queue or any of its dependencies in the error state.";
+  let details = [
+    "If the queue is not in the error state, OL_SUCCESS is written",
+    "Dependencies are created using `olWaitEvents`, if any waited on queue enters the fail state then this will also be in the fail state",
+    "The error is not cleared; there is no way to recover a queue in the error state",
+  ];
+  let params = [
+    Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>,
+    Param<"ol_result_t *", "Error", "output location to put the queue error", PARAM_IN>,
+    Param<"ol_queue_handle_t *", "FailingQueue", "output location to put the queue that encountered an error", PARAM_IN_OPTIONAL>,
+
+  ];
+  let returns = [
+    Return<"OL_ERRC_INVALID_QUEUE">
+  ];
+}

offload/liboffload/src/OffloadImpl.cpp

@@ -644,6 +644,13 @@ Error olGetQueueInfoSize_impl(ol_queue_handle_t Queue, ol_queue_info_t PropName,
   return olGetQueueInfoImplDetail(Queue, PropName, 0, nullptr, PropSizeRet);
 }
 
+Error olGetQueueError_impl(ol_queue_handle_t Queue, ol_result_t *Error,
+                           ol_queue_handle_t *ErrQueue) {
+  // TODO
+  *Error = nullptr;
+  return Error::success();
+}
+
 Error olSyncEvent_impl(ol_event_handle_t Event) {
   // No event info means that this event was complete on creation
   if (!Event->EventInfo)