drm: Document kms locking a bit better

The rules are getting real hard, better to dump my brain into text a
bit. This is by far not complete, but I think I reasonable start at
least.

Some of the older kms structures would need a full doc review anyway
...

Cc: Harry Wentland <harry.wentland@amd.com>
Reviewed-by: Harry Wentland <harry.wentland@amd.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170328155349.5972-2-daniel.vetter@ffwll.ch

1 files changed, 12 insertions, 2 deletions

diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 24dcb121bad4..c1a75a9c81c2 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -699,10 +699,12 @@ struct drm_crtc {
 	/**
 	 * @mutex:
 	 *
-	 * This provides a read lock for the overall crtc state (mode, dpms
+	 * This provides a read lock for the overall CRTC state (mode, dpms
 	 * state, ...) and a write lock for everything which can be update
-	 * without a full modeset (fb, cursor data, crtc properties ...). A full
+	 * without a full modeset (fb, cursor data, CRTC properties ...). A full
 	 * modeset also need to grab &drm_mode_config.connection_mutex.
+	 *
+	 * For atomic drivers specifically this protects @state.
 	 */
 	struct drm_modeset_lock mutex;
 
@@ -748,6 +750,14 @@ struct drm_crtc {
 	 * @state:
 	 *
 	 * Current atomic state for this CRTC.
+	 *
+	 * This is protected by @mutex. Note that nonblocking atomic commits
+	 * access the current CRTC state without taking locks. Either by going
+	 * through the &struct drm_atomic_state pointers, see
+	 * for_each_crtc_in_state(), for_each_oldnew_crtc_in_state(),
+	 * for_each_old_crtc_in_state() and for_each_new_crtc_in_state(). Or
+	 * through careful ordering of atomic commit operations as implemented
+	 * in the atomic helpers, see &struct drm_crtc_commit.
 	 */
 	struct drm_crtc_state *state;