STRUCT XE_PAGEFAULT(9)

✨ struct xe_pagefault (kernel API manual energy) ✨

okay bestie, so this page is literally from the Kernel API Manual — it's the struct xe_pagefault(9) entry — and it's the whole "xe page fault" situation, which sounds scary but is actually so well organized. let's get into it 💅

🌸 NAME 🌸

struct xe_pagefault — Xe page fault. that's it, that's the vibe. it's the struct. it's the page fault. periodt.

✨ SYNOPSIS ✨

here's the whole thing, character for character, no cap — don't let the #defines scare you, they're just chillin' inside the struct:

struct xe_pagefault {
    struct xe_gt *gt;
    struct {
      u64 page_addr;
      u32 asid;
      u8 access_type;
  #define XE_PAGEFAULT_ACCESS_TYPE_MASK   GENMASK(1, 0);
  #define XE_PAGEFAULT_ACCESS_PREFETCH    BIT(7);
      u8 fault_type_level;
  #define XE_PAGEFAULT_TYPE_LEVEL_NACK            0xff    ;
  #define XE_PAGEFAULT_LEVEL_MASK                 GENMASK(3, 0);
  #define XE_PAGEFAULT_TYPE_MASK                  GENMASK(7, 4);
      u8 engine_class;
      u8 engine_instance;
      u64 reserved;
    } consumer;
    struct {
      void *private;
      const struct xe_pagefault_ops *ops;
  #define XE_PAGEFAULT_PRODUCER_MSG_LEN_DW        4;
      u32 msg[XE_PAGEFAULT_PRODUCER_MSG_LEN_DW];
    } producer;
 };

like… she's got two whole nested structs inside her, consumer and producer, and they each have a job. main character energy fr fr 🫶

---

🎀 Members 🎀

• gt — the GT of the fault. that's the graphics tile in question, bestie, so you know exactly who's having the moment.
• consumer — all the state for the software that's handling the fault. it gets populated by the producer, and heads up: the consumer is allowed to modify it, specifically so it can send info back to the producer once the fault gets acknowledged. it's giving two-way communication 💖
  • consumer.page_addr — the address of the page fault 👑
  • consumer.asid — the address space ID
  • consumer.access_type — the access type and the prefetch flag, packed together into one u8. efficient queen.
  • consumer.fault_type_level — the fault type and level, kept as a u8 instead of an enum purely to keep the size compact. lowkey iconic of her.
  • consumer.engine_class — engine class
  • consumer.engine_instance — engine instance
  • consumer.reserved — reserved bits for future expansion 🌈 (future-proofing, we love to see it)
• producer — state for the producer, aka the HW/FW interface. this one is populated by the producer and — listen to me — it should not be modified by the consumer. it shouldn't even be inspected by the consumer, except for the one specific reason of calling operations. so like… hands off, unless you're calling ops. 🙈
  • producer.private — private pointer
  • producer.ops — operations
  • producer.msg — the page fault message. the producer uses it during fault acknowledgment to formulate the response back to the HW/FW interface. and the reason it's baked into the page-fault message at all? because the producer typically catches the fault in a context where it literally cannot allocate memory — think atomic context or the reclaim path. no malloc for you. 😭

---

🦋 Description 🦋

so this is the generic page fault structure, and it exists for communication between the producer and the consumer. she is carefully sized to be 64 bytes — exactly, deliberately, on purpose. 💀

when a device page fault happens, the producer fills this bad boy in, and then the consumer copies it into the page-fault queue so it can be handled later, deferred-style. no rush, no panic, just queue it and slay later. ✨

real talk though: the producer half is read-only for consumers — the manpage says don't modify it, don't even inspect it, except to call operations. that's not a suggestion, that's the contract. 🫶

---

⭐ SEE ALSO ⭐

• Kernel file ./drivers/gpu/drm/xe/xe_pagefault_types.h — struct xe_pagefault_queue(9) (go read that one next, iykyk)

---

and that's the whole page, bestie! source is ./drivers/gpu/drm/xe, from the October 2026 era of the Kernel API Manual, documenting struct xe_pagefault(9). go forth and fault gracefully 💜🦋🎀