drm/atomic: Unconfuse the old_state mess in commmit_tail

I totally butcherd the job on typing the kernel-doc for these, and no
one realized. Noticed by Russell. Maarten has a more complete approach
to this confusion, by making it more explicit what the new/old state
is, instead of this magic switching behaviour.

v2:
- Liviu pointed out that wait_for_fences is even more magic. Leave
that as @state, and document @pre_swap better.
- While at it, patch in header for the reference section.
- Fix spelling issues Russell noticed.

v3: Fix up the @pre_swap note (Liviu): Also s/synchronous/blocking/,
since async flip is something else than non-blocking.

Cc: Liviu Dudau <[email protected]>
Reported-by: Russell King - ARM Linux <[email protected]>
Cc: Russell King - ARM Linux <[email protected]>
Fixes: 9f2a7950e77a ("drm/atomic-helper: nonblocking commit support")
Cc: Gustavo Padovan <[email protected]>
Cc: Maarten Lankhorst <[email protected]>
Cc: Tomeu Vizoso <[email protected]>
Cc: Daniel Stone <[email protected]>
Reviewed-by: Liviu Dudau <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: http://patchwork.freedesktop.org/patch/msgid/[email protected]

1 files changed, 8 insertions, 4 deletions

diff --git a/include/drm/drm_modeset_helper_vtables.h b/include/drm/drm_modeset_helper_vtables.h
index 72478cf82147..69c3974bf133 100644
--- a/include/drm/drm_modeset_helper_vtables.h
+++ b/include/drm/drm_modeset_helper_vtables.h
@@ -999,10 +999,14 @@ struct drm_mode_config_helper_funcs {
 	 * to implement blocking and nonblocking commits easily. It is not used
 	 * by the atomic helpers
 	 *
-	 * This hook should first commit the given atomic state to the hardware.
-	 * But drivers can add more waiting calls at the start of their
-	 * implementation, e.g. to wait for driver-internal request for implicit
-	 * syncing, before starting to commit the update to the hardware.
+	 * This function is called when the new atomic state has already been
+	 * swapped into the various state pointers. The passed in state
+	 * therefore contains copies of the old/previous state. This hook should
+	 * commit the new state into hardware. Note that the helpers have
+	 * already waited for preceeding atomic commits and fences, but drivers
+	 * can add more waiting calls at the start of their implementation, e.g.
+	 * to wait for driver-internal request for implicit syncing, before
+	 * starting to commit the update to the hardware.
 	 *
 	 * After the atomic update is committed to the hardware this hook needs
 	 * to call drm_atomic_helper_commit_hw_done(). Then wait for the upate