[PATCH] drm: writeback: Document behaviour for framebuffer size mismatch

[PATCH] drm: writeback: Document behaviour for framebuffer size mismatch

[Derek Foreman]

Currently we have not explicitly defined the behaviour when the width
and height of the writeback framebuffer do not match the width and
height of the attached CRTC.

Allow the driver to perform a scale operation to fit the content, so
systems with scaling blocks in the writeback path can easily expose them.
Failure remains an option for all the systems that don't have a scaler.

Cropping would make less sense, as the region to crop is underspecified
without some other properties to define an origin.

Signed-off-by: Derek Foreman <derek.foreman@collabora.com>
---

I have a draft merge request against weston for this at:
 https://gitlab.freedesktop.org/wayland/weston/-/merge_requests/2071

 drivers/gpu/drm/drm_writeback.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/gpu/drm/drm_writeback.c b/drivers/gpu/drm/drm_writeback.c
index 4da5d6094721..735a3cdff79a 100644
--- a/drivers/gpu/drm/drm_writeback.c
+++ b/drivers/gpu/drm/drm_writeback.c
@@ -58,6 +58,9 @@
  *	framebuffer to be written by the writeback connector. This property is
  *	similar to the FB_ID property on planes, but will always read as zero
  *	and is not preserved across commits.
+ *	If the width and height of the framebuffer do not match those of the
+ *	attached CRTC, the driver may either fail or scale (not crop) the
+ *	content to fit the framebuffer.
  *	Userspace must set this property to an output buffer every time it
  *	wishes the buffer to get filled.
  *
-- 
2.53.0

Claude review: drm: writeback: Document behaviour for framebuffer size mismatch

[Claude Code Review Bot]

Overall Series Review

Subject: drm: writeback: Document behaviour for framebuffer size mismatch
Author: Derek Foreman <derek.foreman@collabora.com>
Patches: 1
Reviewed: 2026-06-04T12:17:50.607491

---

This is a single documentation-only patch (v2) to the DRM writeback connector subsystem. It adds six lines of kernel-doc commentary to the `WRITEBACK_FB_ID` property documentation in `drm_writeback.c`, specifying what should happen when the writeback framebuffer dimensions differ from the attached CRTC dimensions.

The patch is well-motivated: the existing documentation left this behavior entirely undefined, which is a problem for both driver implementers and userspace (compositors like Weston). The chosen policy — allow scaling, forbid cropping, and require failure over partial fills — is reasonable and pragmatic:

- **Scaling** is the natural operation for hardware with scaler blocks in the writeback path.
- **Cropping** is correctly excluded since there's no property to specify a crop origin.
- **Failure over partial fill** is the safe default, preventing garbage data in the output buffer.

The v2 change (making it explicit that partial fills must not occur) is a good improvement.

No functional code changes, no risk of regressions. This is straightforward UAPI documentation clarification.

**Verdict: Looks good.** Minor wording nit below, but nothing blocking.

---
Generated by Claude Code Patch Reviewer

Claude review: drm: writeback: Document behaviour for framebuffer size mismatch

[Claude Code Review Bot]

Patch Review

**Correctness:** The documentation accurately captures a sensible policy. It properly handles the three possible outcomes for size mismatch: scale (allowed), crop (disallowed), fail (always available as fallback). The "must fail instead of partially filling" language is a good addition in v2.

**Wording nit:** The phrase "an odd width for a sub-sampled format" at line 65:
```
+ *	such as hardware scaler constraints or an odd width for a sub-sampled
+ *	format, the writeback must fail instead of partially filling the buffer.
```
This example is reasonable but slightly tangential — odd-width-with-subsampling is more of a general format constraint issue than something specific to the scaling-vs-mismatch scenario being documented. It's fine as-is since it illustrates "unable to exactly fill," but a reviewer could argue it muddies the focus. Not worth blocking on.

**Integration with existing text:** The new text slots in cleanly between the description of what `WRITEBACK_FB_ID` stores and the instruction that "Userspace must set this property to an output buffer every time...". The flow reads naturally.

**Missing consideration:** The patch doesn't mention whether aspect ratio must be preserved during scaling, or whether arbitrary stretching is permitted. This is presumably left to the driver, which seems fine for now — adding aspect ratio constraints could come in a follow-up if needed.

**Reviewed-by: Looks good to merge.**

---
Generated by Claude Code Patch Reviewer

Claude review: drm: writeback: Document behaviour for framebuffer size mismatch

[Claude Code Review Bot]

Overall Series Review

Subject: drm: writeback: Document behaviour for framebuffer size mismatch
Author: Derek Foreman <derek.foreman@collabora.com>
Patches: 1
Reviewed: 2026-06-04T13:41:03.189082

---

This is a single documentation-only patch that adds three lines to the KDoc comment for the `WRITEBACK_FB_ID` property in `drm_writeback.c`. It specifies the expected behavior when the writeback framebuffer dimensions don't match the CRTC dimensions: the driver may either fail the commit or scale the content (but not crop).

The patch is reasonable and addresses a genuine gap in the writeback connector specification. The rationale in the commit message is sound — cropping is underspecified without an origin/viewport property, while scaling is well-defined.

**Minor concerns:**

1. The wording "the driver may either fail or scale (not crop)" is clear but could be slightly more precise about *when* the failure occurs — it should be at atomic check time, not silently at commit time. A `TEST_ONLY` commit should be able to discover this.

2. There's no mention of whether the scaling should preserve aspect ratio or stretch. For a UAPI doc, it might be worth stating this is implementation-defined, or that the framebuffer dimensions define the output size (i.e., stretch to fit).

3. The patch does not add any helper validation or enforcement in the core — it's purely documenting what drivers are allowed to do. That's fine for now, but a follow-up adding a core helper (e.g., a flag on `drm_writeback_connector` indicating scaling support) would make this more useful and consistent across drivers.

---

---
Generated by Claude Code Patch Reviewer

Claude review: drm: writeback: Document behaviour for framebuffer size mismatch

[Claude Code Review Bot]

Patch Review

**Correctness:** The placement of the new text is appropriate — it's inserted into the `WRITEBACK_FB_ID` property description between the "will always read as zero and is not preserved across commits" sentence and the "Userspace must set this property" sentence. Looking at the existing code at line 60-62:

```
 *	and is not preserved across commits.
 *	Userspace must set this property to an output buffer every time it
```

The new text:
```
 *	If the width and height of the framebuffer do not match those of the
 *	attached CRTC, the driver may either fail or scale (not crop) the
 *	content to fit the framebuffer.
```

This reads well in context and is positioned logically.

**Suggestions:**

- Consider making the failure mode more explicit: "the driver may either fail the atomic commit or scale..." — this clarifies that failure should happen at check time, which is important for userspace doing `TEST_ONLY` commits to probe capabilities.

- It may be worth adding a note about aspect ratio behavior being driver-defined, e.g., "the driver may either fail the atomic commit or scale (not crop) the content to fit the framebuffer; the scaling method is driver-defined."

- The commit message mentions "Cropping would make less sense, as the region to crop is underspecified without some other properties to define an origin." This is good reasoning. It might be worth capturing the "not crop" rationale briefly in the doc itself (or at least confirming the commit message is sufficient for future archaeology).

**Nit:** The subject says "Document behaviour" (British English) — this is fine but note the kernel tends toward American English ("behavior") in most documentation, though it's not strictly enforced.

**Overall:** This is a clean, focused documentation patch. The content is correct and fills a real gap in the UAPI specification. It could benefit from slightly more precise wording around failure mode (at atomic check time) and scaling semantics, but as-is it's a reasonable improvement.

**Verdict:** Looks good with optional wording improvements. Reviewed-by worthy.

---
Generated by Claude Code Patch Reviewer