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

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

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

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
>