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

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

On Mon, 2026-02-23 at 13:39 -0800, Matthew Brost wrote:
> 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.

So this is the observed behavior and what we had been told is the
intent from the architects. But you're right I don't see any explicit
documentation on the GuC side about this. Let me dig and get back here
before we make any changes here...

Thanks,
Stuart

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