1 files changed, 15 insertions, 1 deletions

diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
index 31da9f0c4ad2..7aedbf34f3a6 100644
--- a/include/drm/drm_plane.h
+++ b/include/drm/drm_plane.h
@@ -456,7 +456,6 @@ enum drm_plane_type {
  * @funcs: helper functions
  * @properties: property tracking for this plane
  * @type: type of plane (overlay, primary, cursor)
- * @state: current atomic state for this plane
  * @zpos_property: zpos property for this plane
  * @rotation_property: rotation property for this plane
  * @helper_private: mid-layer private data
@@ -473,6 +472,8 @@ struct drm_plane {
 	 * Protects modeset plane state, together with the &drm_crtc.mutex of
 	 * CRTC this plane is linked to (when active, getting activated or
 	 * getting disabled).
+	 *
+	 * For atomic drivers specifically this protects @state.
 	 */
 	struct drm_modeset_lock mutex;
 
@@ -502,6 +503,19 @@ struct drm_plane {
 
 	const struct drm_plane_helper_funcs *helper_private;
 
+	/**
+	 * @state:
+	 *
+	 * Current atomic state for this plane.
+	 *
+	 * This is protected by @mutex. Note that nonblocking atomic commits
+	 * access the current plane state without taking locks. Either by going
+	 * through the &struct drm_atomic_state pointers, see
+	 * for_each_plane_in_state(), for_each_oldnew_plane_in_state(),
+	 * for_each_old_plane_in_state() and for_each_new_plane_in_state(). Or
+	 * through careful ordering of atomic commit operations as implemented
+	 * in the atomic helpers, see &struct drm_crtc_commit.
+	 */
 	struct drm_plane_state *state;
 
 	struct drm_property *zpos_property;