INIT, G2H-EVENT AND REPORTING FLOWS FOR GUC-ERROR-CAPTURE(9)

🌸 Init, G2H-event and reporting flows for GuC-error-capture (9) 🌸

okay so bestie, this is the Kernel API Manual page for the GuC-error-capture init + G2H-event + reporting flows, section 9 — the whole map, no cap. 💅✨ iykyk

💫 KMD Init time flows 💫

• --> alloc A: GuC input capture regs lists (registered to GuC via ADS).
  • xe_guc_ads acquires the register lists by calling xe_guc_capture_getlistsize and xe_guc_capture_getlist 'n' times, where n = 1 for global-reg-list + num_engine_classes for class-reg-list + num_engine_classes for instance-reg-list (since all instances of the same engine-class type have an identical engine-instance register-list).
  • The ADS module also calls separately for PF vs VF.
• --> alloc B: GuC output capture buf (registered via guc_init_params(log_param)).
  • Size = XE_GUC_LOG_STATE_CAPTURE_BUFFER_SIZE (warns if on too-small).
  • Note2: 'x 3' to hold multiple capture groups.

📡 GUC Runtime notify capture 📡

• --> G2H STATE_CAPTURE_NOTIFICATION
  • L--> xe_guc_capture_process
  • L--> Loop through B (head..tail) and for each engine instance's err-state-captured register-list we find, we alloc 'C':
    • --> alloc C: A capture-output-node structure that includes misc capture info along with 3 register list dumps (global, engine-class and engine-instance).
      • This node is created from a pre-allocated list of blank nodes in guc->capture->cachelist and populated with the error-capture data from GuC and then it's added into guc->capture->outlist linked list.
      • This list is used for matchup and printout by xe_devcoredump_read and xe_engine_snapshot_print, (when user invokes the devcoredump sysfs).

🚨 GUC --> notify context reset 🚨

• --> guc_exec_queue_timedout_job
  • L--> xe_devcoredump
  • L--> devcoredump_snapshot
  • --> xe_hw_engine_snapshot_capture
  • --> xe_engine_manual_capture (For manual capture)

🖥️ User Sysfs / Debugfs 🖥️

• --> xe_devcoredump_read->
  • L--> xxx_snapshot_print
    • L--> xe_engine_snapshot_print
      • Print register lists values saved at guc->capture->outlist.

🔎 SEE ALSO 🔎

• Kernel file ./drivers/gpu/drm/xe/xe_guc_capture.c
• xe_guc_capture_getlistsize(9)
• xe_guc_capture_getlist(9)
• xe_guc_capture_getnullheader(9)
• xe_guc_capture_ads_input_worst_size(9)
• xe_engine_manual_capture(9)
• xe_engine_snapshot_print(9)
• xe_guc_capture_get_matching_and_lock(9)
• xe_engine_snapshot_capture_for_queue(9)

xoxo bestie, source/version ./drivers/gpu/drm/xe, dated October 2026 💖🫶