STANDARD PLANE PROPERTIES(9)

🎀 standard plane properties(9) 🎀

ok so bestie, welcome to the standard plane properties page from the Kernel API Manual — this is the DRM plane lore and honestly it ate 💅

---

✨ DESCRIPTION ✨

so DRM planes have a few standardized properties, and here's the whole rundown no cap:

🌈 type:

Immutable property describing the type of the plane.

here's the tea for user-space that has enabled the DRM_CLIENT_CAP_ATOMIC capability: the plane type is just a hint, and it's mostly superseded by atomic test-only commits. but like, the type hint can still be used to come up more easily with a plane configuration that the driver accepts. lowkey helpful 🫶

The value of this property can be one of the following:

• "Primary" — to light up a CRTC, attaching a primary plane is the most likely to work if it covers the whole CRTC and doesn't have scaling or cropping set up.

Drivers may support more features for the primary plane, and user-space can find out with test-only atomic commits 👀

⚠️ Some primary planes are implicitly used by the kernel in the legacy IOCTLs DRM_IOCTL_MODE_SETCRTC and DRM_IOCTL_MODE_PAGE_FLIP. Therefore user-space must not mix explicit usage of any primary plane (e.g. through an atomic commit) with these legacy IOCTLs. fr fr, don't do it 😭

• "Cursor" — to enable this plane, using a framebuffer configured without scaling or cropping and with the following properties is the most likely to work:
  • If the driver provides the capabilities DRM_CAP_CURSOR_WIDTH and DRM_CAP_CURSOR_HEIGHT, create the framebuffer with this size. Otherwise, create a framebuffer with the size 64x64.
  • If the driver doesn't support modifiers, create a framebuffer with a linear layout. Otherwise, use the IN_FORMATS plane property.

Drivers may support more features for the cursor plane, user-space can find out with test-only atomic commits ✨

⚠️ Some cursor planes are implicitly used by the kernel in the legacy IOCTLs DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2. Therefore user-space must not mix explicit usage of any cursor plane (e.g. through an atomic commit) with these legacy IOCTLs. same energy, don't mix them 💀

Some drivers may support cursors even if no cursor plane is exposed. In this case, the legacy cursor IOCTLs can be used to configure the cursor. iconic behaviour honestly 👑

• "Overlay" — neither primary nor cursor.

Overlay planes are the only planes exposed when the DRM_CLIENT_CAP_UNIVERSAL_PLANES capability is disabled.

🦋 IN_FORMATS:

Blob property which contains the set of buffer format and modifier pairs supported by this plane. The blob is a struct drm_format_modifier_blob. Without this property the plane doesn't support buffers with modifiers. Userspace cannot change this property.

Note that userspace can check the DRM_CAP_ADDFB2_MODIFIERS driver capability for general modifier support. If this flag is set then every plane will have the IN_FORMATS property, even when it only supports DRM_FORMAT_MOD_LINEAR. Before linux kernel release v5.1 there have been various bugs in this area with inconsistencies between the capability flag and per-plane properties 🙈 (so if you're on something ancient… good luck bestie)

🌸 IN_FORMATS_ASYNC:

Blob property which contains the set of buffer format and modifier pairs supported by this plane for asynchronous flips. The blob is a struct drm_format_modifier_blob. Userspace cannot change this property. This is an optional property and if not present then user should expect a failure in atomic ioctl when the modifier/format is not supported by that plane under asynchronous flip 👀

⭐ SIZE_HINTS:

Blob property which contains the set of recommended plane size which can used for simple "cursor like" use cases (eg. no scaling). Using these hints frees userspace from extensive probing of supported plane sizes through atomic/setcursor ioctls. literally the biggest time-saver 🫶

The blob contains an array of struct drm_plane_size_hint, in order of preference. For optimal usage userspace should pick the first size that satisfies its own requirements 💖

Drivers should only attach this property to planes that support a very limited set of sizes.

Note that property value 0 (ie. no blob) is reserved for potential future use. Current userspace is expected to ignore the property if the value is 0, and fall back to some other means (eg. DRM_CAP_CURSOR_WIDTH and DRM_CAP_CURSOR_HEIGHT) to determine the appropriate plane size to use.

---

👑 SEE ALSO 👑

go read these next bestie, the whole friend group:

• Kernel file ./drivers/gpu/drm/drm_plane.c
• overview(9)
• hotspot properties(9)
• drm_plane_create_hotspot_properties(9)
• drm_universal_plane_init(9)
• drm_plane_cleanup(9)
• drm_plane_from_index(9)
• drm_plane_force_disable(9)
• drm_mode_plane_set_obj_prop(9)
• drm_plane_has_format(9)
• drm_any_plane_has_format(9)
• damage tracking(9)
• drm_plane_enable_fb_damage_clips(9)
• drm_plane_get_damage_clips_count(9)
• drm_plane_get_damage_clips(9)
• drm_plane_create_scaling_filter_property(9)
• drm_plane_add_size_hints_property(9)
• drm_plane_create_color_pipeline_property(9)

---

ok that's the whole page, mwah 💋 this one's from ./drivers/gpu/drm, dated October 2026 — slay, go configure some planes, and remember: don't mix legacy IOCTLs with your atomic commits, i'm begging 🎀✨