Re: [PATCH v3 16/18] drm/xe/doc: Add documentation for Multi Queue Group

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

On Thu, Nov 20, 2025 at 07:51:50PM -0800, Niranjana Vishwanathapura wrote:
> Add kernel documentation for Multi Queue group and update
> the corresponding rst.
> 
> Signed-off-by: Niranjana Vishwanathapura <niranjana.vishwanathapura@intel.com>

Reviewed-by: Matthew Brost <matthew.brost@intel.com>

> ---
>  Documentation/gpu/xe/xe_exec_queue.rst |  6 ++++
>  drivers/gpu/drm/xe/xe_exec_queue.c     | 45 ++++++++++++++++++++++++++
>  2 files changed, 51 insertions(+)
> 
> diff --git a/Documentation/gpu/xe/xe_exec_queue.rst b/Documentation/gpu/xe/xe_exec_queue.rst
> index 6076569e311c..732af4741df4 100644
> --- a/Documentation/gpu/xe/xe_exec_queue.rst
> +++ b/Documentation/gpu/xe/xe_exec_queue.rst
> @@ -7,6 +7,12 @@ Execution Queue
>  .. kernel-doc:: drivers/gpu/drm/xe/xe_exec_queue.c
>     :doc: Execution Queue
>  
> +Multi Queue Group
> +=================
> +
> +.. kernel-doc:: drivers/gpu/drm/xe/xe_exec_queue.c
> +   :doc: Multi Queue Group
> +
>  Internal API
>  ============
>  
> diff --git a/drivers/gpu/drm/xe/xe_exec_queue.c b/drivers/gpu/drm/xe/xe_exec_queue.c
> index 839fb08f09e7..50326b4431e0 100644
> --- a/drivers/gpu/drm/xe/xe_exec_queue.c
> +++ b/drivers/gpu/drm/xe/xe_exec_queue.c
> @@ -54,6 +54,51 @@
>   * the ring operations the different engine classes support.
>   */
>  
> +/**
> + * DOC: Multi Queue Group
> + *
> + * Multi Queue Group is another mode of execution supported by the compute
> + * and blitter copy command streamers (CCS and BCS, respectively). It is
> + * an enhancement of the existing hardware architecture and leverages the
> + * same submission model. It enables support for efficient, parallel
> + * execution of multiple queues within a single shared context. The multi
> + * queue group functionality is only supported with GuC submission backend.
> + * All the queues of a group must use the same address space (VM).
> + *
> + * The DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_QUEUE execution queue property
> + * supports creating a multi queue group and adding queues to a queue group.
> + *
> + * The XE_EXEC_QUEUE_CREATE ioctl call with above property with value field
> + * set to DRM_XE_MULTI_GROUP_CREATE, will create a new multi queue group with
> + * the queue being created as the primary queue (aka q0) of the group. To add
> + * secondary queues to the group, they need to be created with the above
> + * property with id of the primary queue as the value. The properties of
> + * the primary queue (like priority, time slice) applies to the whole group.
> + * So, these properties can't be set for secondary queues of a group.
> + *
> + * The hardware does not support removing a queue from a multi-queue group.
> + * However, queues can be dynamically added to the group. A group can have
> + * up to 64 queues. To support this, XeKMD holds references to LRCs of the
> + * queues even after the queues are destroyed by the user until the whole
> + * group is destroyed. The secondary queues hold a reference to the primary
> + * queue thus preventing the group from being destroyed when user destroys
> + * the primary queue. Once the primary queue is destroyed, secondary queues
> + * can't be added to the queue group, but they can continue to submit the
> + * jobs if the DRM_XE_MULTI_GROUP_KEEP_ACTIVE flag is set during the multi
> + * queue group creation.
> + *
> + * The queues of a multi queue group can set their priority within the group
> + * through the DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_QUEUE_PRIORITY property.
> + * This multi queue priority can also be set dynamically through the
> + * XE_EXEC_QUEUE_SET_PROPERTY ioctl. This is the only other property
> + * supported by the secondary queues of a multi queue group, other than
> + * DRM_XE_EXEC_QUEUE_SET_PROPERTY_MULTI_QUEUE.
> + *
> + * When GuC reports an error on any of the queues of a multi queue group,
> + * the queue cleanup mechanism is invoked for all the queues of the group
> + * as hardware cannot make progress on the multi queue context.
> + */
> +
>  enum xe_exec_queue_sched_prop {
>  	XE_EXEC_QUEUE_JOB_TIMEOUT = 0,
>  	XE_EXEC_QUEUE_TIMESLICE = 1,
> -- 
> 2.43.0
>