DAMAGE TRACKING(9)

✨ damage tracking ✨

okay bestie, so this one is a page from the Kernel API Manual (section 9, kernel-flavored, very demure very mindful) and it's literally all about FB_DAMAGE_CLIPS. let's get into it 💅

---

🌸 DESCRIPTION 🌸

so FB_DAMAGE_CLIPS is an optional plane property — key word optional, we'll get there — and what it does is give you a way to specify a list of damage rectangles on a plane, in framebuffer coordinates of the framebuffer attached to the plane. fancy.

in the current context, "damage" means the area of the plane framebuffer that has changed since the last plane update (aka the page-flip, iykyk) — and this is true irrespective of whether the currently attached framebuffer is the same as the framebuffer attached during the last plane update. same fb, different fb, doesn't matter. the definition holds. periodt.

FB_DAMAGE_CLIPS is basically a hint to the kernel 🫶 and it can genuinely help some drivers optimize internally — especially virtual devices where every single framebuffer change has to be transmitted over network, usb, etc. like, imagine shipping the whole screen over USB every frame. no thank you.

since FB_DAMAGE_CLIPS is a hint, it is an optional property. user-space can straight up ignore the damage clips property, and in that case the driver will just do a full plane update. totally valid, no drama.

but if damage clips are provided, then it is guaranteed that the area inside the damage clips will be updated to the plane. slay. however — and this is the important part — for efficiency a driver can do a full update, or can update more than what's specified in the damage clips. so because the driver is free to read more, user-space must always render the entire visible framebuffer. otherwise there can be corruptions. 😭

and also — if a user-space provides damage clips that don't encompass the actual damage to the framebuffer (since the last plane update), that can result in incorrect rendering. so like… be accurate, bestie.

FB_DAMAGE_CLIPS is a blob property, and the layout of the blob data is simply an array of drm_mode_rect. unlike the plane drm_plane_state.src coordinates, damage clips are not in 16.16 fixed point. similar to plane src in framebuffer, damage clips cannot be negative. and inside a damage clip, x1/y1 are inclusive and x2/y2 are exclusive — classic half-open interval moment, we love a boundary convention. 🌈

the kernel does not error out for overlapped damage clips, but it's strongly discouraged. like, it'll let you, but it's giving messy. don't.

---

🦋 for the driver girlies 🦋

drivers that are interested in the damage interface for a plane should enable the FB_DAMAGE_CLIPS property by calling drm_plane_enable_fb_damage_clips. ✨

drivers implementing damage can use the drm_atomic_helper_damage_iter_init and drm_atomic_helper_damage_iter_next helper iterator functions to get damage rectangles clipped to drm_plane_state.src. cute little iterator duo, they ate.

---

🎀 the two types of damage handling 🎀

okay so note that there are two types of damage handling: frame damage and buffer damage. which type of damage handling is implemented depends on a driver's upload target.

• drivers implementing a per-plane or per-CRTC upload target need to handle frame damage
• drivers implementing a per-buffer upload target need to handle buffer damage

and ngl, the existing damage helpers only support the frame damage type. there is no buffer age support or similar damage accumulation algorithm implemented yet. so if that's what you need… not yet, bestie. 🙈

only drivers handling frame damage can use the mentioned damage helpers to iterate over the damaged regions.

drivers that handle buffer damage must set drm_plane_state.ignore_damage_clips so that drm_atomic_helper_damage_iter_init knows that damage clips should be ignored and returns drm_plane_state.src as the damage rectangle — which forces a full plane update. 💀

---

💜 per-buffer upload target girlies, listen up 💜

drivers with a per-buffer upload target could compare the drm_plane_state.fb of the old and new plane states to determine if the framebuffer attached to a plane has changed or not since the last plane update. and if drm_plane_state.fb has changed, then drm_plane_state.ignore_damage_clips must be set to true. no exceptions, no vibes-based skipping.

why? because drivers with a per-plane upload target expect the backing storage buffer to not change for a given plane. if the upload buffer changes between page flips, the new upload buffer has to be updated as a whole. like, the entire thing. main character energy, it demands full attention. 👑

and yeah, this can be improved in the future if support for frame damage is added to the DRM damage helpers, similarly to how user-space already handles this case — as it is explained in the following documents:

https://registry.khronos.org/EGL/extensions/KHR/EGL_KHR_swap_buffers_with_damage.txt
https://emersion.fr/blog/2019/intro-to-damage-tracking/

go read them, they're iconic. 📚

---

⭐ SEE ALSO ⭐

• kernel file ./drivers/gpu/drm/drm_plane.c overview(9)
• standard plane properties(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)
• 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)

---

and that's the whole page, bestie!! 🫶 this lil beauty lives in ./drivers/gpu/drm, dated October 2026 — go off, damage tracking, we're obsessed 💖✨