STRUCT INTEL_GUC(9)

💖 struct intel_guc(9) 💖

okay so bestie, welcome to the top level structure of GuC — like, the main character of the whole GuC situation in the i915 driver. this page lives in the Kernel API Manual, and honestly? it's giving "one struct to rule them all" energy. let's get into it 🫶

---

✨ NAME ✨

struct intel_guc — Top level structure of GuC. periodt.

---

🌈 SYNOPSIS 🌈

struct intel_guc {
    struct intel_uc_fw fw;
    struct intel_guc_log log;
    struct intel_guc_ct ct;
    struct intel_guc_slpc slpc;
    struct intel_guc_state_capture *capture;
    struct dentry *dbgfs_node;
    struct i915_sched_engine *sched_engine;
    struct i915_request *stalled_request;
    enum {
      STALL_NONE,
      STALL_REGISTER_CONTEXT,
      STALL_MOVE_LRC_TAIL,
      STALL_ADD_REQUEST,
    } submission_stall_reason;
    spinlock_t irq_lock;
    unsigned int msg_enabled_mask;
    atomic_t outstanding_submission_g2h;
    struct xarray tlb_lookup;
    u32 serial_slot;
    u32 next_seqno;
    struct {
      bool enabled;
      void (*reset)(struct intel_guc *guc);
      void (*enable)(struct intel_guc *guc);
      void (*disable)(struct intel_guc *guc);
    } interrupts;
    struct {
      spinlock_t lock;
      struct ida guc_ids;
      int num_guc_ids;
      unsigned long *guc_ids_bitmap;
      struct list_head guc_id_list;
      unsigned int guc_ids_in_use;
      struct list_head destroyed_contexts;
      struct work_struct destroyed_worker;
      struct work_struct reset_fail_worker;
      intel_engine_mask_t reset_fail_mask;
      unsigned int sched_disable_delay_ms;
      unsigned int sched_disable_gucid_threshold;
    } submission_state;
    bool submission_supported;
    bool submission_selected;
    bool submission_initialized;
    struct intel_uc_fw_ver submission_version;
    bool rc_supported;
    bool rc_selected;
    struct i915_vma *ads_vma;
    struct iosys_map ads_map;
    u32 ads_regset_size;
    u32 ads_regset_count[I915_NUM_ENGINES];
    struct guc_mmio_reg *ads_regset;
    u32 ads_golden_ctxt_size;
    u32 ads_waklv_size;
    u32 ads_capture_size;
    struct i915_vma *lrc_desc_pool_v69;
    void *lrc_desc_pool_vaddr_v69;
    struct xarray context_lookup;
    u32 params[GUC_CTL_MAX_DWORDS];
    struct {
      u32 base;
      unsigned int count;
      enum forcewake_domains fw_domains;
    } send_regs;
    i915_reg_t notify_reg;
    u32 mmio_msg;
    struct mutex send_mutex;
    struct {
      spinlock_t lock;
      u64 gt_stamp;
      unsigned long ping_delay;
      struct delayed_work work;
      u32 shift;
      unsigned long last_stat_jiffies;
    } timestamp;
    struct work_struct dead_guc_worker;
    unsigned long last_dead_guc_jiffies;
  #ifdef CONFIG_DRM_I915_SELFTEST;
    int number_guc_id_stolen;
    u32 fast_response_selftest;
  #endif;
   };

---

💅 MEMBERS 💅

okay this is the long part and yes we're doing all of them, no skipping, i would never do that to you 💜

• fw — the GuC firmware. the whole reason we're here, lowkey.
• log — sub-structure containing GuC log related data and objects.
• ct — the command transport communication channel. the group chat between host and GuC, fr.
• slpc — sub-structure containing SLPC related data and objects.
• capture — the error-state-capture module's data and objects.
• dbgfs_node — debugfs node.
• sched_engine — Global engine used to submit requests to GuC. main character energy, honestly.
• stalled_request — if GuC can't process a request for any reason, we save it until GuC restarts processing. No other request can be submitted until the stalled request is processed. like a queue of one, and everyone else waits 💀
• submission_stall_reason — reason why submission is stalled.
• irq_lock — protects GuC irq state.
• msg_enabled_mask — mask of events that are processed when receiving an INTEL_GUC_ACTION_DEFAULT G2H message.
• outstanding_submission_g2h — number of outstanding GuC to Host responses related to GuC submission, used to determine if the GT is idle.
• tlb_lookup — xarray to store all pending TLB invalidation requests.
• serial_slot — id to the initial waiter created in tlb_lookup, which is used only when failed to allocate new waiter.
• next_seqno — the next id (sequence number) to allocate.
• interrupts — pointers to GuC interrupt-managing functions.
• submission_state — sub-structure for submission state protected by single lock.
• submission_state.lock — protects everything in submission_state, ce->guc_id.id, and ce->guc_id.ref when transitioning in and out of zero.
• submission_state.guc_ids — used to allocate new guc_ids, single-lrc.
• submission_state.num_guc_ids — Number of guc_ids, selftest feature to be able to reduce this number while testing.
• submission_state.guc_ids_bitmap — used to allocate new guc_ids, multi-lrc.
• submission_state.guc_id_list — list of intel_context with valid guc_ids but no refs.
• submission_state.guc_ids_in_use — Number single-lrc guc_ids in use.
• submission_state.destroyed_contexts — list of contexts waiting to be destroyed (deregistered with the GuC).
• submission_state.destroyed_worker — worker to deregister contexts, need as we need to take a GT PM reference and can't from destroy function as it might be in an atomic context (no sleeping). she needs her own little thread, ok? no sleeping on the job 😴
• submission_state.reset_fail_worker — worker to trigger a GT reset after an engine reset fails.
• submission_state.reset_fail_mask — mask of engines that failed to reset.
• submission_state.sched_disable_delay_ms — schedule disable delay, in ms, for contexts.
• submission_state.sched_disable_gucid_threshold — threshold of min remaining available guc_ids before we start bypassing the schedule disable delay.
• submission_supported — tracks whether we support GuC submission on the current platform.
• submission_selected — tracks whether the user enabled GuC submission.
• submission_initialized — tracks whether GuC submission has been initialised.
• submission_version — Submission API version of the currently loaded firmware.
• rc_supported — tracks whether we support GuC rc on the current platform.
• rc_selected — tracks whether the user enabled GuC rc.
• ads_vma — object allocated to hold the GuC ADS.
• ads_map — contents of the GuC ADS.
• ads_regset_size — size of the save/restore regsets in the ADS.
• ads_regset_count — number of save/restore registers in the ADS for each engine.
• ads_regset — save/restore regsets in the ADS.
• ads_golden_ctxt_size — size of the golden contexts in the ADS.
• ads_waklv_size — size of workaround KLVs.
• ads_capture_size — size of register lists in the ADS used for error capture.
• lrc_desc_pool_v69 — object allocated to hold the GuC LRC descriptor pool.
• lrc_desc_pool_vaddr_v69 — contents of the GuC LRC descriptor pool.
• context_lookup — used to resolve intel_context from guc_id, if a context is present in this structure it is registered with the GuC.
• params — Control params for fw initialization.
• send_regs — GuC's FW specific registers used for sending MMIO H2G.
• notify_reg — register used to send interrupts to the GuC FW.
• mmio_msg — notification bitmask that the GuC writes in one of its registers when the CT channel is disabled, to be processed when the channel is back up.
• send_mutex — used to serialize the intel_guc_send actions.
• timestamp — GT timestamp object that stores a copy of the timestamp and adjusts it for overflow using a worker.
• timestamp.lock — Lock protecting the below fields and the engine stats.
• timestamp.gt_stamp — 64-bit extended value of the GT timestamp.
• timestamp.ping_delay — Period for polling the GT timestamp for overflow.
• timestamp.work — Periodic work to adjust GT timestamp, engine and context usage for overflows.
• timestamp.shift — Right shift value for the gpm timestamp.
• timestamp.last_stat_jiffies — jiffies at last actual stats collection time. We use this timestamp to ensure we don't oversample the stats because runtime power management events can trigger stats collection at much higher rates than required. not me oversampling the stats 😭
• dead_guc_worker — Asynchronous worker thread for forcing a GuC reset. Specifically used when the G2H handler wants to issue a reset. Resets require flushing the G2H queue. So, the G2H processing itself must not trigger a reset directly. Instead, go via this worker. like, do NOT do it yourself, route it through the worker bestie 🙈
• last_dead_guc_jiffies — timestamp of previous 'dead guc' occurrence used to prevent a fundamentally broken system from continuously reloading the GuC. rate limiting, but for chaos 💀
• number_guc_id_stolen — The number of guc_ids that have been stolen.
• fast_response_selftest — Backdoor to CT handler for fast response selftest.

---

🦋 DESCRIPTION 🦋

so what does this icon actually do? It handles firmware loading and manages client pool. and intel_guc owns an i915_sched_engine for submission. that's it, that's the vibe check ⭐

---

🌸 SEE ALSO 🌸

• Kernel file ./drivers/gpu/drm/i915/gt/uc/intel_guc.h
• intel_guc_ggtt_offset(9)

---

and that's the whole page, no cap 💖 this one shipped from ./drivers/gpu/drm/i915/gt/uc, dated October 2026, and it's the struct intel_guc(9) page — go off, king 👑✨🎀