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

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

On Mon, Feb 23, 2026 at 02:56:53PM -0700, Summers, Stuart wrote:
> 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...
> 

I would double check as I'm near positive what I wrote above was correct
at least when the new GuC interface (v69 major version) was implemented.
Ofc this could have changed in the last 5 years though.

Matt 

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