append_oa_sample(9)

💅 append_oa_sample(9) 💅

Okay bestie, this is append_oa_sample(9) straight out of the Kernel API Manual. It’s giving kernel-perf fairy vibes, it’s lowkey iconic, and it’s literally about copying one single OA report into the userspace read() buffer. 💖

🎀 NAME 🎀

append_oa_sample — copies a single OA report into the userspace read() buffer. ✨

✨ SYNOPSIS ✨

int append_oa_sample (struct i915_perf_stream *stream , char __user *buf
       , size_t count , size_t *offset , const u8 *report );

🦋 ARGUMENTS 🦋

• stream — an i915-perf stream opened for OA metrics, the main character here. 👑
• buf — the destination buffer given by userspace.
• count — the number of bytes userspace wants to read.
• offset — (inout) the current position for writing into buf; yes, it’s an inout situation, track it carefully.
• report — a single OA report to (optionally) include as part of the sample.

🌸 DESCRIPTION 🌸

So the contents of a sample are configured through DRM_I915_PERF_PROP_SAMPLE_* properties when opening a stream, and those are tracked as stream->sample_flags. This function copies the requested components of a single sample into the given read buf. Simple? Mostly. iykyk. 🫶

Important vibe check: the buf offset will only be updated on success. No accidental offset glow-up on failure, periodt. 💅

🔥 RETURN 🔥

0 on success, negative error code on failure. That’s it, that’s the return tea. 😭

🌈 SEE ALSO 🌈

Kernel file: ./drivers/gpu/drm/i915/i915_perf.c. Here’s the full squad of references, every single one, no cap:

• i915 Perf Overview(9)
• i915 Perf History and Comparison with Core Perf(9)
• OA Tail Pointer Race(9)
• struct perf_open_properties(9)
• oa_buffer_check_unlocked(9)
• append_oa_status(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)

Source/version + date sign-off: ./drivers/gpu/drm/i915 · October 2026 · append_oa_sample(9) — mwah, bestie 💋🎀