summaryrefslogtreecommitdiff
path: root/include/drm/drm_plane.h
diff options
context:
space:
mode:
authorSimon Ser <contact@emersion.fr>2019-10-09 15:10:49 +0000
committerDaniel Vetter <daniel.vetter@ffwll.ch>2019-10-09 20:04:55 +0200
commit8f6ea27b2fefdff58b3a038b5f1b4ed34aed3fd3 (patch)
tree403197175f328ddf2a94a018948b4b74248f446f /include/drm/drm_plane.h
parentf2a4a13ab2ca3605010d72c774b6aab3ba1a09f4 (diff)
drm: two planes with the same zpos have undefined ordering
Currently the property docs don't specify whether it's okay for two planes to have the same zpos value and what user-space should expect in this case. The unspoken, legacy rule used in the past was to make user-space figure out the zpos from object IDs. However some drivers break this rule, that's why the ordering is documented as unspecified in case the zpos property is missing. User-space should rely on the zpos property only. There are some cases in which user-space might read identical zpos values for different planes. For instance, in case the property is mutable, user-space might set two planes' zpos to the same value. This is necessary to support user-space using the legacy DRM API where atomic commits are not possible: user-space needs to update the planes' zpos one by one. Because of this, user-space should handle multiple planes with the same zpos. While at it, remove the assumption that zpos is only for overlay planes. Additionally, update the drm_plane_state.zpos docs to clarify that zpos disambiguation via plane object IDs is a recommendation for drivers, not something user-space can rely on. In other words, when user-space sets the same zpos on two planes, drivers should rely on the plane object ID. v2: clarify drm_plane_state.zpos docs (Daniel) v3: zpos is for all planes (Marius, Daniel) v4: completely reword the drm_plane_state.zpos docs to make it clear the recommendation to use plane IDs is for drivers in case user-space uses duplicate zpos values (Pekka) v5: reword commit message (Pekka, James) v6: remove mention of Arm GPUs having planes which can't overlap, because this isn't uAPI yet (Daniel) Signed-off-by: Simon Ser <contact@emersion.fr> Reviewed-by: Pekka Paalanen <ppaalanen@gmail.com> Cc: Marius Vlad <marius.vlad@collabora.com> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: James Qian Wang <james.qian.wang@arm.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Link: https://patchwork.freedesktop.org/patch/msgid/T5nHrvXH0GKOp6ONaFHk-j2cwEb4_4C_sBz9rNw8mmPACuut-DQqC74HMAFKZH3_Q15E8a3YnmKCxap-djKA71VVZv_T-tFxaB0he13O7yA=@emersion.fr
Diffstat (limited to 'include/drm/drm_plane.h')
-rw-r--r--include/drm/drm_plane.h9
1 files changed, 5 insertions, 4 deletions
diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
index cd5903ad33f7..328773690851 100644
--- a/include/drm/drm_plane.h
+++ b/include/drm/drm_plane.h
@@ -140,10 +140,11 @@ struct drm_plane_state {
* @zpos:
* Priority of the given plane on crtc (optional).
*
- * Note that multiple active planes on the same crtc can have an
- * identical zpos value. The rule to solving the conflict is to compare
- * the plane object IDs; the plane with a higher ID must be stacked on
- * top of a plane with a lower ID.
+ * User-space may set mutable zpos properties so that multiple active
+ * planes on the same CRTC have identical zpos values. This is a
+ * user-space bug, but drivers can solve the conflict by comparing the
+ * plane object IDs; the plane with a higher ID is stacked on top of a
+ * plane with a lower ID.
*
* See drm_plane_create_zpos_property() and
* drm_plane_create_zpos_immutable_property() for more details.