STRUCT DRM_XE_QUERY_ENGINE_CYCLES(9)

🌸 struct drm_xe_query_engine_cycles — the correlation station 💅

okay so bestie, you're reading the Kernel API Manual page for struct drm_xe_query_engine_cycles, and honestly? it's giving "let me match your CPU clock to your GPU clock so we can vibe in sync" ✨ no cap. let's get into it 🫶

---

✨ NAME ✨

struct drm_xe_query_engine_cycles — correlate CPU and GPU timestamps 🕰️💖

like, literally that's its whole job. matching timestamps. iconic.

---

🦋 SYNOPSIS 🦋

struct drm_xe_query_engine_cycles {
    struct drm_xe_engine_class_instance eci;
    __s32 clockid;
    __u32 width;
    __u64 engine_cycles;
    __u64 cpu_timestamp;
    __u64 cpu_delta;
 };

look at her. six fields. perfect. no notes 💅

---

🎀 Members (the cast, the main characters) 🎀

• eci — okay so this one is input by the user 👈 and it's the engine you want the command streamer cycles for. like, you're telling the kernel "this one, bestie."
• clockid — also input by the user 👈 and it's the reference clock id for the CPU timestamp. for the actual definition, go see clock_gettime(2) and perf_event_open(2) — iykyk. the supported clock ids are CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW, CLOCK_REALTIME, CLOCK_BOOTTIME, and CLOCK_TAI ⏱️ slay.
• width — the width of the engine cycle counter, in bits. tiny detail, big importance 💀
• engine_cycles — engine cycles, read straight from its register at the 0x358 offset. that's the number, periodt 📍
• cpu_timestamp — CPU timestamp in ns 🕐. this one gets captured before the engine_cycles register is read, using that reference clockid you set yourself. you did that. you're the main character.
• cpu_delta — time delta in ns, captured around reading the lower dword of the engine_cycles register. yes, specifically the lower dword. she's precise 🌸

---

💜 Description 💜

so here's the tea ☕ — if you make a query with a struct drm_xe_device_query where .query is equal to DRM_XE_DEVICE_QUERY_ENGINE_CYCLES, then the reply comes back using struct drm_xe_query_engine_cycles in .data 📦. and yes, the struct drm_xe_query_engine_cycles is allocated by the user, with .data pointing at that allocated structure. you own that memory, bestie 🫵

the query returns the engine cycles, which — along with the GT's reference_clock — can be used to calculate the engine timestamp 🔥. and as a little bonus, the query also returns a set of CPU timestamps that tell you when the command streamer cycle count was captured. it's giving receipts. it's giving synchronized. we love a timestamp that knows its own context 💖

---

🌈 SEE ALSO 🌈

go read these, i'm obsessed with cross-references:

• Kernel file ./include/uapi/drm/xe_drm.h 📄
• Xe Device Block Diagram(9)
• Xe uAPI Overview(9)
• Xe IOCTL Extensions(9)
• struct drm_xe_user_extension(9)
• struct drm_xe_ext_set_property(9)
• struct drm_xe_engine_class_instance(9)
• struct drm_xe_engine(9)
• struct drm_xe_query_engines(9)
• enum drm_xe_memory_class(9)
• struct drm_xe_mem_region(9)
• struct drm_xe_query_mem_regions(9)
• struct drm_xe_query_config(9)
• struct drm_xe_gt(9)
• struct drm_xe_query_gt_list(9)
• struct drm_xe_query_topology_mask(9)
• struct drm_xe_query_uc_fw_version(9)
• struct drm_xe_query_pxp_status(9)
• struct drm_xe_device_query(9)
• struct drm_xe_gem_create(9)
• struct drm_xe_gem_mmap_offset(9)
• struct drm_xe_vm_create(9)
• struct drm_xe_vm_destroy(9)
• struct drm_xe_vm_bind_op(9)
• struct drm_xe_vm_bind(9)
• struct drm_xe_vm_get_property(9)
• struct drm_xe_exec_queue_create(9)
• struct drm_xe_exec_queue_destroy(9)
• struct drm_xe_exec_queue_get_property(9)
• struct drm_xe_sync(9)
• struct drm_xe_exec(9)
• struct drm_xe_wait_user_fence(9)
• enum drm_xe_observation_type(9)
• enum drm_xe_observation_op(9)
• struct drm_xe_observation_param(9)
• enum drm_xe_observation_ioctls(9)
• enum drm_xe_oa_unit_type(9)
• struct drm_xe_oa_unit(9)
• struct drm_xe_query_oa_units(9)
• enum drm_xe_oa_format_type(9)
• enum drm_xe_oa_property_id(9)
• struct drm_xe_oa_config(9)
• struct drm_xe_oa_stream_status(9)
• struct drm_xe_oa_stream_info(9)
• enum drm_xe_pxp_session_type(9)
• enum drm_xe_eu_stall_property_id(9)
• struct drm_xe_query_eu_stall(9)
• struct drm_xe_madvise(9)
• struct drm_xe_mem_range_attr(9)
• struct drm_xe_vm_query_mem_range_attr(9)
• struct drm_xe_exec_queue_set_property(9)
• Xe DRM RAS(9)
• enum drm_xe_ras_error_severity(9)
• enum drm_xe_ras_error_component(9)

---

💀 reminder bestie: eci and clockid are inputs — you fill those in. the rest is the kernel handing you the receipts. don't get it twisted.

---

and that's the page!! 🎀 from ./include/uapi/drm, dated October 2026 — go off, timestamps, go off 👑✨ bye bestie, ily, drink water 🦋💜