[PATCH] drm/xe: Document exec queue priority rules

[Stuart Summers <stuart.summers@intel.com>]

Add some documentation around how the GuC will employ
the xe_exec_queue priorities provided by userspace
application.

Signed-off-by: Stuart Summers <stuart.summers@intel.com>
---
 drivers/gpu/drm/xe/xe_exec_queue_types.h | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/drivers/gpu/drm/xe/xe_exec_queue_types.h b/drivers/gpu/drm/xe/xe_exec_queue_types.h
index 3791fed34ffa..aefebfc6996e 100644
--- a/drivers/gpu/drm/xe/xe_exec_queue_types.h
+++ b/drivers/gpu/drm/xe/xe_exec_queue_types.h
@@ -22,6 +22,30 @@ struct xe_guc_exec_queue;
 struct xe_hw_engine;
 struct xe_vm;
 
+/**
+ * enum xe_exec_queue_priority - Exec Queue priority values
+ *
+ * XeKMD uses GuC as the primary submission vehicle to HW.
+ * GuC has 4 priority levels that roughly map to the 4 levels
+ * shown here but in reverse order. GuC scheduler uses time
+ * slicing to determine how long a queue should remain on the
+ * command streamer before issuing a preemption request to
+ * allow execution of another queue.
+ *
+ * The following rules should be considered by applications
+ * employing these queue priorities:
+ *  - A HIGH priority request will preempt a NORMAL and LOW
+ *    priority request when submitted and based on the time
+ *    slice quantum.
+ *  - A NORMAL priority request will preempt a LOW priority
+ *    request when submitted and based on that time slice
+ *    quantum but will not preempt a HIGH priority request
+ *    until that time slice quantum has been reached.
+ *  - A LOW priority request will never preempt either a
+ *    MEDIUM or HIGH priority context.
+ *  - Currently KERNEL level priority is reserved, as the name
+ *    suggests, for kernel-submitted queues only.
+ */
 enum xe_exec_queue_priority {
 	XE_EXEC_QUEUE_PRIORITY_UNSET = -2, /* For execlist usage only */
 	XE_EXEC_QUEUE_PRIORITY_LOW = 0,
-- 
2.34.1