kgd_gfx_v12_...cu_occupancy(9)

💖 kgd_gfx_v12_1_get_cu_occupancy — Kernel API Manual edition 🎀

okay so bestie, welcome to the <pink>Kernel API Manual</pink> ✨ and honestly? this one is a whole mood. it's kgd_gfx_v12_...cu_occupancy(9) (the full function name is kgd_gfx_v12_1_get_cu_occupancy, yes the header is doing that little abbreviation thing, we love her anyway 💅).

---

🌸 NAME 🌸

kgd_gfx_v12_1_get_cu_occupancy — reads the relevant registers that are associated with each shader engine, and aggregates the number of waves that are in flight for the process whose pasid is passed in as a parameter 🦋. and like, no big deal, but that process could have <hotpink>ZERO</hotpink> or more queues running and submitting waves to compute units. zero. or more. the range is giving "anything is possible" energy fr fr 💀

---

⭐ SYNOPSIS ⭐

void kgd_gfx_v12_1_get_cu_occupancy (struct amdgpu_device *adev , struct
kfd_cu_occupancy *cu_occupancy , int *max_waves_per_cu , uint32_t inst );

---

✨ ARGUMENTS ✨

• adev — handle of the device you're pulling the number of waves in flight from 🫶
• cu_occupancy — the array that gets filled with wave_cnt and the doorbell offset, so you can compare stuff later 💜
• max_waves_per_cu — output parameter, gets updated with the maximum number of waves possible per Compute Unit 👑
• inst — the xcc's instance number, for when you're on a multi-XCC setup 🌈

---

🎀 NOTE 🎀

🚨 bestie listen. it's possible that the device has <red>too many queues</red> (that's oversubscription, iykyk) and in that case a VMID could get remapped to a different PASID. and that? that could lead to an <red>inaccurate wave count</red> 😭. here's the high-level sequence, laid out for you:

1. Time T1: vmid = getVmid — the vmid is associated with Pasid P1
2. Time T2: passId = getPasId(vmid) — the vmid is associated with Pasid P2

so in that sequence up there, the wave count you got from time T1 will be <yellow>incorrectly lost or added to the total wave count</yellow>. not the vibe. 💀

the registers that provide the waves in flight are:

• SPI_CSQ_WF_ACTIVE_STATUS — a bit-map of queues per pipe 🧚. the bit is <green>ON</green> if a queue is slotted, <red>OFF</red> if there's no queue at all. a process could have ZERO or more queues slotted and submitting waves to be run on compute units. and even when there is a queue, it's possible there could be zero wave fronts — that happens when the queue is waiting on top-of-pipe events, like a waitRegMem command, for example 🍓

for each bit that's ON from the above:

• read the (SPI_CSQ_WF_ACTIVE_COUNT_0 + queue_idx) register 💖. it gives you the number of waves that are in flight for the queue at that specified index, and the index ranges from 0 to 7
• if there are non-zero waves in flight, store the corresponding doorbell offset of the queue, along with the wave count 🎀
• determine if the queue belongs to the process by comparing the doorbell offset against the process's queues. if it matches, aggregate the wave count for the process ✅
• reading the registers referenced above involves programming GRBM appropriately, that's just how it is ⭐

---

🦋 SEE ALSO 🦋

• Kernel file ./drivers/gpu/drm/amd/amdgpu/amdgpu_amdkfd_gfx_v12_1.c
• get_wave_count(9)

---

and that's the whole page bestie, no cap, every last detail intact 💅✨

this little icon came out of the source <cyan>./drivers/gpu/drm/amd/amdgpu</cyan> and it's stamped <mint>October 2026</mint> — so like, shoutout to the manual, she's dated and she's slaying 🫶🎀