MULTI QUEUE GROUP GUC INTERFACE(9)

💅 Multi Queue Group GuC interface 💅

okay bestie, you're reading the Kernel API Manual page Multi Queue...uC interface(9) — yes the header is literally truncated like that, that's just how it renders, we move 💖

So here's the tea: the multi queue group coordination between KMD and GuC goes through a software construct called the Context Group Page (CGP). The CGP is a KMD managed 4KB page, and it's allocated in the global GTT. slay.

---

🎀 CGP format 🎀

one bullet per DWORD row so literally nothing gets lost, periodt:

• DWORD 0 — Version — bits [15:8]=Major ver, [7:0]=Minor ver
• DWORD 1..15 — RESERVED — MBZ
• DWORD 16 — KMD_QUEUE_UPDATE_MASK_DW0 — KMD queue mask for queues 31..0
• DWORD 17 — KMD_QUEUE_UPDATE_MASK_DW1 — KMD queue mask for queues 63..32
• DWORD 18..31 — RESERVED — MBZ
• DWORD 32 — Q0CD_DW0 — Queue 0 context LRC descriptor lower DWORD
• DWORD 33 — Q0ContextIndex — Context ID for Queue 0
• DWORD 34 — Q1CD_DW0 — Queue 1 context LRC descriptor lower DWORD
• DWORD 35 — Q1ContextIndex — Context ID for Queue 1
• DWORD 158 — Q63CD_DW0 — Queue 63 context LRC descriptor lower DWORD
• DWORD 159 — Q63ContextIndex — Context ID for Queue 63
• DWORD 160..1024 — RESERVED — MBZ

and yes the list jumps straight from 35 to 158, no I'm not okay either 😭 just so you're not jumpscared.

---

🦋 how the registering actually goes 🦋

While registering Q0 with GuC, the CGP gets updated with the Q0 entry, and GuC is notified through the XE_GUC_ACTION_REGISTER_CONTEXT_MULTI_QUEUE H2G message — which specifies the CGP address. iconic.

When the secondary queues are added to the group, the CGP is updated with the entry for that queue, and GuC is notified through the H2G interface XE_GUC_ACTION_MULTI_QUEUE_CONTEXT_CGP_SYNC.

GuC responds to these H2G messages with a XE_GUC_ACTION_NOTIFY_MULTIQ_CONTEXT_CGP_SYNC_DONE G2H message. 🫶

GuC also sends a XE_GUC_ACTION_NOTIFY_MULTI_QUEUE_CGP_CONTEXT_ERROR notification for any error in the CGP. not the error notification 😭

⚠️ okay this part matters: only one of these CGP update messages can be outstanding (waiting for GuC response) at any time. one at a time, bestie. the bits in the KMD_QUEUE_UPDATE_MASK_DW* fields indicate which queue entry is being updated in the CGP.

The primary queue (Q0) represents the multi queue group context in GuC, and submission on any queue of the group must be through the Q0 GuC interface only. no detours, no side quests 💅

And since it is not required to register secondary queues with GuC, the secondary queue context ids in the CGP are populated with the Q0 context id. cute, efficient, we love a shortcut that's actually legal ✨

---

🌈 SEE ALSO 🌈

Kernel file ./drivers/gpu/drm/xe/xe_guc_submit.c plus the whole friend group:

• xe_guc_submit_init(9)
• xe_guc_submit_wedge(9)
• xe_guc_submit_pause(9)
• xe_guc_submit_pause_vf(9)
• xe_guc_submit_unpause_prepare_vf(9)
• xe_guc_submit_unpause(9)
• xe_guc_submit_unpause_vf(9)
• xe_guc_submit_pause_abort(9)
• xe_guc_exec_queue_cgp_sync_done_handler(9)
• xe_guc_exec_queue_snapshot_capture(9)
• xe_guc_exec_queue_snapshot_capture_delayed(9)
• xe_guc_exec_queue_snapshot_print(9)
• xe_guc_exec_queue_snapshot_free(9)
• xe_guc_register_vf_exec_queue(9)
• xe_guc_submit_print(9)
• xe_guc_has_registered_mlrc_queues(9)
• xe_guc_contexts_hwsp_rebase(9)

---

mwah, that's the whole page 🎀 this came from ./drivers/gpu/drm/xe, dated October 2026, and the footer still calls it Multi Queue...uC interface(9) — go read it again if you need to, i'll be right here 🫶💜