STRUCT GUC_LOG_BUFFER_STATE(9)

✨ NAME ✨

so this page is from the Kernel API Manual, and it's all about struct guc_log_buffer_state — which is literally the GuC log buffer state 💅

---

🦋 SYNOPSIS 🦋

okay bestie, here's the whole struct, character for character, no edits, periodt:

struct guc_log_buffer_state {
    u32 marker[2];
    u32 read_ptr;
    u32 write_ptr;
    u32 size;
    u32 sampled_write_ptr;
    u32 wrap_offset;
    u32 flags;
  #define GUC_LOG_BUFFER_STATE_FLUSH_TO_FILE      GENMASK(0, 0);
  #define GUC_LOG_BUFFER_STATE_BUFFER_FULL_CNT    GENMASK(4, 1);
    u32 version;
 };

---

🎀 MEMBERS 🎀

• marker — the start marker of the buffer state, like the little "you are here" pin at the top of the map 🎯
• read_ptr — the last byte offset that was read by KMD previously
• write_ptr — the next byte offset location that will be written by GuC
• size — the log buffer size
• sampled_write_ptr — the log buffer write pointer 💫 this one is written by GuC to the byte offset of the next free entry in the buffer, on log buffer half full or state capture notification
• wrap_offset — the wraparound offset 🌀 this is the byte offset of the location 1 byte after the last valid guc log event entry written by Guc firmware, before there was a wraparound. This field gets updated by guc firmware and should be used by Host when copying buffer contents to file, iykyk
• flags — the flush to file flag and buffer full count
• version — the Guc-Log-Entry format version

---

💖 DESCRIPTION 💖

okay so, the state structure below is used for coordination of retrieval of GuC firmware logs, and a separate state is maintained for each log buffer type 🫶

read_ptr points to the location where Xe read last in the log buffer, and it's read only for GuC firmware. Meanwhile write_ptr is incremented by GuC with the number of bytes written for each log entry, and it's read only for Xe. Two pointers, two owners, iconic division of labour, no cap.

When any type of log buffer becomes half full, GuC sends a flush interrupt 🔥 GuC firmware expects that while it is writing to the 2nd half of the buffer, the first half would get consumed by Host and then get a flush completed acknowledgment from Host, so that it does not end up doing any overwrite causing loss of logs. So when the buffer gets half filled & Xe has requested for interrupt, GuC will set the flush_to_file field, set the sampled_write_ptr to the value of write_ptr and raise the interrupt 📣

On receiving the interrupt, Xe should read the buffer, clear the flush_to_file field and also update read_ptr with the value of sample_write_ptr, before sending an acknowledgment to GuC. That whole lil handshake? chef's kiss, but you gotta do all the steps or it breaks 💀

The marker & version fields are for internal usage of GuC and are opaque to Xe. And the buffer_full_cnt field is incremented every time GuC detects the log buffer overflow 🙈

---

🌈 SEE ALSO 🌈

• Kernel file ./drivers/gpu/drm/xe/abi/guc_log_abi.h
• GuC Log buffer Layout(9)

---

and that's the whole vibe check, bestie 🌸 this lil page comes to you from ./drivers/gpu/drm/xe/abi, dated October 2026, and yes it's still struct guc_log_buffer_state(9) — go forth and read those firmware logs responsibly, mwah 💜