OA TAIL POINTER RACE(9)

OA Tail Pointer Race(9) 💅✨

okay bestie, you're reading the Kernel API Manual page for OA Tail Pointer Race, and she is highkey a hardware race condition icon. 🎀 Buckle up.

There's a HW race condition between OA unit tail pointer register updates and writes to memory. Basically, the tail pointer can sometimes get ahead of what's been written out to the OA buffer so far — in terms of what's visible to the CPU. 💀

You can observe this explicitly while copying reports to userspace by checking for a zeroed report-id field in tail reports. But we want to account for it earlier, as part of the oa_buffer_check_unlocked to avoid lots of redundant read attempts. 🙈

We workaround this issue in oa_buffer_check_unlocked by reading the reports in the OA buffer, starting from the tail reported by the HW until we find a report with its first 2 dwords not 0. That means its previous report is completely in memory and ready to be read. ✨ Those dwords are also set to 0 once read, and the whole buffer is cleared upon OA buffer initialization. The first dword is the reason for this report while the second is the timestamp, making the chances of having those 2 fields at 0 fairly unlikely. A more detailed explanation is available in oa_buffer_check_unlocked. 🫶

Most of the implementation details for this workaround are in oa_buffer_check_unlocked and _append_oa_reports. 👑

Note for posterity: previously the driver used to define an effective tail pointer that lagged the real pointer by a 'tail margin' measured in bytes derived from OA_TAIL_MARGIN_NSEC and the configured sampling frequency. This was flawed considering that the OA unit may also automatically generate non-periodic reports (such as on context switch) or the OA unit may be enabled without any periodic sampling. 😭

✨ SEE ALSO ✨

Kernel file ./drivers/gpu/drm/i915/i915_perf.c

• i915 Perf Overview(9)
• i915 Perf History and Comparison with Core Perf(9)
• struct perf_open_properties(9)
• oa_buffer_check_unlocked(9)
• append_oa_status(9)
• append_oa_sample(9)
• gen8_append_oa_reports(9)
• gen8_oa_read(9)
• gen7_append_oa_reports(9)
• gen7_oa_read(9)
• i915_oa_wait_unlocked(9)
• i915_oa_poll_wait(9)
• i915_oa_read(9)
• oa_get_render_ctx_id(9)
• oa_put_render_ctx_id(9)
• i915_oa_stream_enable(9)
• i915_oa_stream_disable(9)
• i915_oa_stream_init(9)
• i915_perf_read(9)
• i915_perf_poll_locked(9)
• i915_perf_poll(9)
• i915_perf_enable_locked(9)
• i915_perf_disable_locked(9)
• i915_perf_ioctl_locked(9)
• i915_perf_ioctl(9)
• i915_perf_destroy_locked(9)
• i915_perf_release(9)
• i915_perf_open_ioctl_locked(9)
• read_properties_unlocked(9)
• i915_perf_open_ioctl(9)
• i915_perf_register(9)
• i915_perf_unregister(9)
• i915_perf_add_config_ioctl(9)
• i915_perf_remove_config_ioctl(9)
• i915_perf_init(9)
• i915_perf_fini(9)
• i915_perf_ioctl_version(9)

mwah 💋 — with love from ./drivers/gpu/drm/i915, October 2026.