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

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

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

Ok there's a new(ish) yield policy that covers this in the GuC spec but
it looks like by default this is not enabled (and of course we aren't
configuring this in the KMD today). I'm tracking down the requirement
here. If we need this change I'll include the documentation from this
patch with that yield policy change in the driver so it's clear.
Otherwise I agree with what you said. Let's hold on this patch until
then.

Thanks,
Stuart

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