Re: [PATCH 7/7] drm/xe/doc: Add GuC submission kernel-doc

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

On Mon, 2025-10-20 at 15:05 -0700, Matthew Brost wrote:
> On Mon, Oct 20, 2025 at 09:45:29PM +0000, Stuart Summers wrote:
> > Add some documentation for the different roles played by the XeKMD
> > in communication with the GuC through exec queue management and
> > the DRM scheduler.
> > 
> 
> I've written fairly detailed GuC submission documentation but it
> stuck
> in review purgatory. Here is the most recent post [1].

Oh excellent I hadn't realized this was part of that series. Happy to
drop mine... I'll also take a look at your patch.

Thanks,
Stuart

> 
> Matt
> 
> [1]
> https://patchwork.freedesktop.org/patch/677980/?series=154627&rev=4 
> 
> > Signed-off-by: Stuart Summers <stuart.summers@intel.com>
> > ---
> >  Documentation/gpu/xe/index.rst         |  1 +
> >  Documentation/gpu/xe/xe_guc_submit.rst |  8 +++
> >  drivers/gpu/drm/xe/xe_guc_submit.c     | 70
> > ++++++++++++++++++++++++++
> >  3 files changed, 79 insertions(+)
> >  create mode 100644 Documentation/gpu/xe/xe_guc_submit.rst
> > 
> > diff --git a/Documentation/gpu/xe/index.rst
> > b/Documentation/gpu/xe/index.rst
> > index bc432c95d1a3..030268ddba87 100644
> > --- a/Documentation/gpu/xe/index.rst
> > +++ b/Documentation/gpu/xe/index.rst
> > @@ -15,6 +15,7 @@ DG2, etc is provided to prototype the driver.
> >     xe_map
> >     xe_migrate
> >     xe_exec_queue
> > +   xe_guc_submit
> >     xe_cs
> >     xe_pm
> >     xe_gt_freq
> > diff --git a/Documentation/gpu/xe/xe_guc_submit.rst
> > b/Documentation/gpu/xe/xe_guc_submit.rst
> > new file mode 100644
> > index 000000000000..a82b5d57ee6a
> > --- /dev/null
> > +++ b/Documentation/gpu/xe/xe_guc_submit.rst
> > @@ -0,0 +1,8 @@
> > +.. SPDX-License-Identifier: (GPL-2.0+ OR MIT)
> > +
> > +==============
> > +GuC Submission
> > +==============
> > +
> > +.. kernel-doc:: drivers/gpu/drm/xe/xe_guc_submit.c
> > +   :doc: GuC Submission
> > diff --git a/drivers/gpu/drm/xe/xe_guc_submit.c
> > b/drivers/gpu/drm/xe/xe_guc_submit.c
> > index a11ae4e70809..fd05f73cd96b 100644
> > --- a/drivers/gpu/drm/xe/xe_guc_submit.c
> > +++ b/drivers/gpu/drm/xe/xe_guc_submit.c
> > @@ -46,6 +46,76 @@
> >  #include "xe_trace.h"
> >  #include "xe_vm.h"
> >  
> > +/**
> > + * DOC: GuC Submission
> > + *
> > + * The primary submission vehicle for the XeKMD is the GuC
> > firmware.
> > + * This includes creating, registering, and submitting exec queues
> > + * (see :ref:`execution-queue`). Once submitted, actual hardware
> > scheduling
> > + * is handled fully by the GuC.
> > + *
> > + * To facilitate these operations, XeKMD makes use of the DRM
> > scheduler
> > + * to handle state changes and determine when jobs should be
> > scheduled
> > + * with the GuC.
> > + *
> > + * Queue Registration
> > + * ==================
> > + *
> > + * Registration and deregistration of exec queues with the GuC
> > involves
> > + * creation of the ring (LRC) for that context. These are
> > asynchronous
> > + * actions by the XeKMD which completes that
> > registration/deregistration
> > + * process once the GuC responds that the hardware registration
> > has
> > + * completed.
> > + *
> > + * Queue Submission
> > + * ================
> > + *
> > + * The GuC has a parameter for each context indicating whether
> > that
> > + * context can be scheduled with the associated engine. After
> > registration
> > + * has completed, the KMD, typically as a reaction to a request
> > from
> > + * the user exec IOCTL call, will issue a schedule request with
> > the
> > + * GuC. The GuC will then add that to its schedule for contexts
> > + * and will in turn schedule this with the command streamer based
> > + * on time slice availability.
> > + *
> > + * Queue Destruction
> > + * =================
> > + *
> > + * As mentioned above, before destroying a queue, it must first be
> > + * deregistered. In the typical case, this happens first by
> > sending
> > + * a schedule disable request, then on confirmation from the GuC,
> > + * a deregistration request. Only after that deregistration
> > response
> > + * will the XeKMD free resources associated with that queue such
> > as
> > + * the LRC.
> > + *
> > + * Engine Resets
> > + * =============
> > + *
> > + * Any time more than one context is being scheduled by the GuC,
> > the GuC
> > + * will give each context a certain configurable time slice. If a
> > context
> > + * exceeds this time slice, the GuC will reset the engine and
> > notify the XeKMD
> > + * along with an engine state at the time of the reset. The XeKMD
> > will then
> > + * resubmit any outstanding jobs to that engine. If a particular
> > job has been
> > + * resubmitted in this way more than once, the associated exec
> > queue will be
> > + * marked banned and will no longer be schedulable on that engine.
> > + *
> > + * Queue Wedging
> > + * =============
> > + *
> > + * On device wedging (see :ref:`device-wedging`), each exec queue
> > is also marked
> > + * as wedged. This includes taking a reference to that device and
> > adding a
> > + * dereference on driver teardown. This additional reference
> > allows a user
> > + * to collect certain debug information about the exec queue prior
> > to driver
> > + * unbind.
> > + *
> > + * There are some instances where the device wedge might not take
> > a reference
> > + * in this way, for instance, if the context is in the process of
> > being
> > + * deregistered with the GuC at the time of the wedge. In this
> > case, a
> > + * reference to that exec queue should already be available and
> > any
> > + * associated data structures will be cleaned up later in the
> > teardown
> > + * sequence.
> > + */
> > +
> >  static struct xe_guc *
> >  exec_queue_to_guc(struct xe_exec_queue *q)
> >  {
> > -- 
> > 2.34.1
> >