blob: e8f4fc405213aaa5b4eed4eb44277e324cb379b2 [file] [edit]
//===-- Queue.td - Queue definitions for Offload -----------*- tablegen -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file contains Offload API definitions related to the queue handle
//
//===----------------------------------------------------------------------===//
def olCreateQueue : Function {
let desc = "Create a queue that can be used to submit work to a device.";
let details = [
"`olCreateQueue` creates a queue on `Device` and stores its handle in "
"`Queue`.",
"The queue belongs to the context passed as `Context`.",
"`Device` must be one of the devices of `Context`.",
"The queue can only be used with resources (memory allocations, "
"programs) created in `Context`.",
"The caller owns the returned queue and must release it with a "
"subsequent call to `olDestroyQueue`.",
"`Context` and `Device` must remain valid for the lifetime of the "
"queue. If `Context` is destroyed first, the queue is left in an "
"undefined state and must not be used.",
"The new queue may reuse the backend resources of a queue that was "
"destroyed earlier on the same device in the same context.",
"`olCreateQueue` is thread safe."
];
let params = [
Param<"ol_context_handle_t", "Context", "context the queue belongs to", PARAM_IN>,
Param<"ol_device_handle_t", "Device", "device the queue submits work to", PARAM_IN>,
Param<"ol_queue_handle_t*", "Queue", "receives the handle of the created queue", PARAM_OUT>
];
let returns = [
Return<"OL_ERRC_INVALID_DEVICE", [
"`Device` does not belong to `Context`"
]>,
Return<"OL_ERRC_UNKNOWN", [
"The queue being reused is in an error state"
]>
];
}
def olDestroyQueue : Function {
let desc = "Destroy a queue.";
let details = [
"`olDestroyQueue` releases `Queue`. After a successful call the handle "
"is invalid and must not be used.",
"Work submitted before the call is not cancelled and runs to "
"completion. `olDestroyQueue` does not wait for it.",
"Events created from `Queue` remain valid and can still be passed to "
"`olSyncEvent`, `olWaitEvents` and `olDestroyEvent`.",
"Backend resources of a queue that still has work pending might be "
"released later, at the latest when its associated context is destroyed.",
"If `olDestroyQueue` fails, `Queue` is not released. It is left in an "
"undefined state and must not be used, including in another call to "
"`olDestroyQueue`.",
"May be called concurrently with calls that operate on other queues. "
"The caller must ensure that no other thread uses `Queue` during or "
"after the call."
];
let params = [
Param<"ol_queue_handle_t", "Queue", "queue to destroy", PARAM_IN>
];
let returns = [];
}
def olSyncQueue : Function {
let desc = "Block the calling thread until the enqueued work on a queue is complete.";
let details = [];
let params = [
Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>
];
let returns = [];
}
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`.",
];
let params = [
Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>,
Param<"ol_event_handle_t *", "Events", "list of `NumEvents` events to wait for", PARAM_IN>,
Param<"size_t", "NumEvents", "size of `Events`", PARAM_IN>,
];
let returns = [
Return<"OL_ERRC_INVALID_NULL_HANDLE", ["Any event handle in the list is NULL"]>,
];
}
def ol_queue_info_t : Enum {
let desc = "Supported queue info.";
let is_typed = 1;
let etors = [
TaggedEtor<"DEVICE", "ol_device_handle_t", "The device that was passed to `olCreateQueue`.">,
TaggedEtor<"CONTEXT", "ol_context_handle_t", "The context that was passed to `olCreateQueue`.">,
TaggedEtor<"EMPTY", "bool", "True if all work submitted to the queue has completed.">,
TaggedEtor<"NATIVE_HANDLE", "void *", "The backend-native handle of the queue, reinterpreted as a void pointer. It is owned by the platform, must not be released by the caller, and is valid only while the queue exists.">,
];
}
def olGetQueueInfo : Function {
let desc = "Query a property of a queue.";
let details = [
"`olGetQueueInfo` writes the value of the property `PropName` of `Queue` "
"to `PropValue`.",
"`PropSize` is the size in bytes of the storage pointed to by "
"`PropValue`. It must be at least the number of bytes that "
"`olGetQueueInfo` needs to store the value of `PropName`, which "
"`olGetQueueInfoSize` reports. A larger `PropSize` is accepted.",
"`ol_queue_info_t` describes each property.",
"`olGetQueueInfo` is thread safe."
];
let params = [
Param<"ol_queue_handle_t", "Queue", "queue to query", PARAM_IN>,
Param<"ol_queue_info_t", "PropName", "property to retrieve", PARAM_IN>,
Param<"size_t", "PropSize", "size in bytes of the storage pointed to by `PropValue`", PARAM_IN>,
TypeTaggedParam<"void*", "PropValue", "receives the property value", PARAM_OUT,
TypeInfo<"PropName" , "PropSize">>
];
let returns = [
Return<"OL_ERRC_INVALID_SIZE", [
"`PropSize == 0`",
"`PropSize` is smaller than the size of the result"
]>,
Return<"OL_ERRC_INVALID_ENUMERATION", [
"`PropName` is not a valid `ol_queue_info_t` value"
]>,
Return<"OL_ERRC_UNSUPPORTED", [
"`PropName` is not supported by the platform"
]>
];
}
def olGetQueueInfoSize : Function {
let desc = "Query the storage size of a queue property.";
let details = [
"`olGetQueueInfoSize` writes to `PropSizeRet` the number of bytes that "
"`olGetQueueInfo` needs to return the property `PropName` of `Queue`.",
"`olGetQueueInfoSize` is thread safe."
];
let params = [
Param<"ol_queue_handle_t", "Queue", "queue to query", PARAM_IN>,
Param<"ol_queue_info_t", "PropName", "property to query", PARAM_IN>,
Param<"size_t*", "PropSizeRet", "receives the required size in bytes", PARAM_OUT>
];
let returns = [
Return<"OL_ERRC_INVALID_ENUMERATION", [
"`PropName` is not a valid `ol_queue_info_t` value"
]>,
Return<"OL_ERRC_UNSUPPORTED", [
"`PropName` is not supported by the platform"
]>
];
}
def ol_host_function_cb_t : FptrTypedef {
let desc = "Host function for use by `olLaunchHostFunction`.";
let params = [
Param<"void *", "UserData", "user specified data passed into `olLaunchHostFunction`.", PARAM_IN>,
];
let return = "void";
}
def olLaunchHostFunction : Function {
let desc = "Enqueue a callback function on the host.";
let details = [
"The provided function will be called from the same process as the one that called `olLaunchHostFunction`.",
"The callback will not run until all previous work submitted to the queue has completed.",
"The callback must return before any work submitted to the queue after it is started.",
"The callback must not call any liboffload API functions or any backend specific functions (such as Cuda or HSA library functions).",
];
let params = [
Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>,
Param<"ol_host_function_cb_t", "Callback", "the callback function to call on the host", PARAM_IN>,
Param<"void *", "UserData", "a pointer that will be passed verbatim to the callback function", PARAM_IN_OPTIONAL>,
];
let returns = [];
}
def olQueryQueue : Function {
let desc = "Query for queue work completion in a non-blocking manner.";
let details = [
"The function checks if a queue work has completed enqueued work without blocking the calling thread."
];
let params = [
Param<"ol_queue_handle_t", "Queue", "handle of the queue", PARAM_IN>,
Param<"bool *", "IsQueueWorkCompleted", " A flag indicating if the queue work has completed", PARAM_OUT_OPTIONAL>
];
let returns = [];
}