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

[Matthew Brost <matthew.brost@intel.com>]

On Mon, Feb 23, 2026 at 09:24:42PM +0000, Stuart Summers wrote:
> 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:

I don’t think this is correct, but Daniele or someone on the GuC team
can correct me if I’m wrong.

My understanding is:

- Queues at the same priority are timesliced. The timeslice quantum
controls how long each queue gets to run before a preempt is
attempted.

- Queues with a higher priority than the one currently running
immediately preempt the lower priority ones. The preemption quantum
controls how long we wait before the lower priority queue is reset if
it doesn’t respond to a preempt.

- If a queue is running at a higher priority, those with lower priority
never get scheduled.

This is why setting HIGH is dangerous — it can completely starve out
other queues, which is why we don’t let unprivileged userspace set it.

Matt

> + *  - 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
>