Commit 9a3e975d authored by Niranjana Vishwanathapura's avatar Niranjana Vishwanathapura
Browse files

drm/xe/doc: Add documentation for Multi Queue Group 



Add kernel documentation for Multi Queue group and update
the corresponding rst.

Signed-off-by: default avatarNiranjana Vishwanathapura <niranjana.vishwanathapura@intel.com>
Reviewed-by: default avatarMatthew Brost <matthew.brost@intel.com>
Link: https://patch.msgid.link/20251211010249.1647839-35-niranjana.vishwanathapura@intel.com
parent 3131a43e

Documentation/gpu/xe/xe_exec_queue.rst

+6 −0
Original line number Diff line number Diff line
@@ -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

============

drivers/gpu/drm/xe/xe_exec_queue.c

+45 −0
Original line number Diff line number Diff line
@@ -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,