kgd_gfx_v9_get_cu_occupancy(9)

💖 kgd_gfx_v9_get_cu_occupancy(9) 💖

okay so bestie, this page is from the Kernel API Manual, and it's giving register-reading main character energy. we're counting waves in flight for a process by pasid, and the vibes are extremely compute-unit. 💅

✨ NAME ✨

kgd_gfx_v9_get_cu_occupancy — reads the relevant registers for every shader engine, then aggregates the number of waves that are in flight for the process whose pasid is provided as a parameter. that process could have ZERO or more queues running and submitting waves to compute units. 🌀

💅 SYNOPSIS 💅

void kgd_gfx_v9_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 from which to get the number of waves in flight.
• cu_occupancy — array that gets filled with wave_cnt and doorbell offset for comparison later.
• max_waves_per_cu — output parameter updated with the maximum number of waves possible per Compute Unit.
• inst — the xcc's instance number on a multi-XCC setup.

⚠️ NOTE ⚠️

okay so lowkey important: it's possible that the device has too many queues (oversubscription), and in that case a VMID could be remapped to a different PASID. that could lead to an inaccurate wave count. 😭 the high-level sequence is:

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

in the sequence above, the wave count obtained from time T1 will be incorrectly lost or added to total wave count. periodt.

🌸 the registers that provide the waves in flight are 🌸

• SPI_CSQ_WF_ACTIVE_STATUS — bit-map of queues per pipe. the bit is ON if a queue is slotted, OFF if there is no queue. a process could have ZERO or more queues slotted and submitting waves to be run on compute units. even when there is a queue, it's possible there could be zero wave fronts; this can happen when the queue is waiting on top-of-pipe events — e.g. the waitRegMem command.

🦋 for each bit that is ON from above 🦋

• read the (SPI_CSQ_WF_ACTIVE_COUNT_0 + queue_idx) register. it provides the number of waves that are in flight for the queue at the specified index. the index ranges from 0 to 7.
• if non-zero waves are 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. 👑

👀 SEE ALSO 👀

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

---

mwah 💋 source/version: ./drivers/gpu/drm/amd/amdgpu · date: October 2026 · page: kgd_gfx_v9_get_cu_occupancy(9) — bye bestie, go read some registers responsibly 🫶✨