INTRODUCTION TO THE ASAHI UAPI(9)

✨ Introduction to the Asahi UAPI ✨

Okay bestie, welcome to the Introduction...e Asahi UAPI(9) page 💖 — literally the crib notes for the Asahi driver's kernel API manual, and honestly it's giving "house rules" energy.

This documentation describes the Asahi IOCTLs. That's it, that's the vibe 🦋

🌸 The generic rules (cribbed from Panthor, no cap)

So like... there are just a few generic rules about the data you pass to the Asahi IOCTLs. Read them, memorize them, live them 💅

• Structures must be aligned on 64-bit/8-byte. If the object isn't naturally aligned, a padding field must be added. Yes, you have to add it yourself. Slay responsibly 🎀
• Fields must be explicitly aligned to their natural type alignment using pad[0..N] fields. Explicit > implicit, periodt ✨
• All padding fields will be checked by the driver to make sure they are zeroed. Not "should be", will be — the driver is literally checking, so don't try it 🙈
• Flags can be added, but not removed/replaced. Once a flag is in the group chat, it stays in the group chat 💀
• New fields can be added to the main structures (the structures directly passed to the ioctl). Those fields can go at the end of the structure, or replace existing padding fields. But — and this is the important part, bestie — any new field being added must preserve the behavior that existed before those fields were added when a value of zero is passed. Zero must stay the boring, backwards-compatible value 🫶
• New fields can be added to indirect objects (objects pointed by the main structure), iff those objects are passed a size to reflect the size known by the userspace driver (see drm_asahi_cmd_header::size). iykyk 👑
• If the kernel driver is too old to know some fields, those will be ignored if zero, and otherwise rejected (and so will be zero on output). Old kernel = strict bouncer at the club 🔥
• If userspace is too old to know some fields, those will be zeroed (input) before the structure is parsed by the kernel driver. Mutual grace, we love to see it 🌈
• Each new flag/field addition must come with a driver version update so the userspace driver doesn't have to guess which flags are supported. No guessing games, bestie — version it properly ⭐
• Structures should not contain unions, as this would defeat the extensibility of such structures. Unions are not invited to this party 😭
• IOCTLs can't be removed or replaced. New IOCTL IDs should be placed at the end of the drm_asahi_ioctl_id enum. Append-only, forever and always 💜

🦋 SEE ALSO

Kernel file ./include/uapi/drm/asahi_drm.h and its whole friend group 💖:

• enum drm_asahi_ioctl_id(9)
• struct drm_asahi_params_global(9)
• enum drm_asahi_feature(9)
• struct drm_asahi_get_params(9)
• struct drm_asahi_vm_create(9)
• struct drm_asahi_vm_destroy(9)
• enum drm_asahi_gem_flags(9)
• struct drm_asahi_gem_create(9)
• struct drm_asahi_gem_mmap_offset(9)
• enum drm_asahi_bind_flags(9)
• struct drm_asahi_gem_bind_op(9)
• struct drm_asahi_vm_bind(9)
• enum drm_asahi_bind_object_op(9)
• enum drm_asahi_bind_object_flags(9)
• struct drm_asahi_gem_bind_object(9)
• enum drm_asahi_cmd_type(9)
• enum drm_asahi_priority(9)
• struct drm_asahi_queue_create(9)
• struct drm_asahi_queue_destroy(9)
• enum drm_asahi_sync_type(9)
• struct drm_asahi_sync(9)
• DRM_ASAHI_BARRIER_NONE(9)
• struct drm_asahi_cmd_header(9)
• struct drm_asahi_submit(9)
• struct drm_asahi_attachment(9)
• struct drm_asahi_zls_buffer(9)
• struct drm_asahi_timestamp(9)
• struct drm_asahi_timestamps(9)
• struct drm_asahi_helper_program(9)
• struct drm_asahi_bg_eot(9)
• struct drm_asahi_cmd_render(9)
• struct drm_asahi_cmd_compute(9)
• struct drm_asahi_get_time(9)
• DRM_IOCTL_ASAHI(9)

💡 Friendly reminder from your local Unix girlie: every single one of these is a real reference, so go read them before you go poking at the kernel. She bites 💅

Okay that's the whole page, bestie 🌸 — brought to you from ./include/uapi/drm, October 2026, under the title Introduction...e Asahi UAPI(9). Mwah 🫶🎀