drm/bridge: Improve kerneldoc
Especially document the assumptions and semantics of the callbacks
carefully. Just a warm-up excercise really.
v2: Spelling fixes (Eric).
v3: Consolidate more with existing docs:
- Remove the overview section explaining the bridge funcs, that's
now all in the drm_bridge_funcs kerneldoc in much more detail.
- Use & to reference structs so that kerneldoc automatically inserts
hyperlinks.
v4: Review from Thierry.
Cc: Eric Anholt <eric@anholt.net>
Cc: Archit Taneja <architt@codeaurora.org>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Archit Taneja <architt@codeaurora.org> (v3)
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-7-git-send-email-daniel.vetter@ffwll.ch
Reviewed-by: Thierry Reding <treding@nvidia.com>
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index e8f8e4e..7f80fae 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -883,24 +883,114 @@
/**
* struct drm_bridge_funcs - drm_bridge control functions
* @attach: Called during drm_bridge_attach
- * @mode_fixup: Try to fixup (or reject entirely) proposed mode for this bridge
- * @disable: Called right before encoder prepare, disables the bridge
- * @post_disable: Called right after encoder prepare, for lockstepped disable
- * @mode_set: Set this mode to the bridge
- * @pre_enable: Called right before encoder commit, for lockstepped commit
- * @enable: Called right after encoder commit, enables the bridge
*/
struct drm_bridge_funcs {
int (*attach)(struct drm_bridge *bridge);
+
+ /**
+ * @mode_fixup:
+ *
+ * This callback is used to validate and adjust a mode. The paramater
+ * mode is the display mode that should be fed to the next element in
+ * the display chain, either the final &drm_connector or the next
+ * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
+ * requires. It can be modified by this callback and does not need to
+ * match mode.
+ *
+ * This is the only hook that allows a bridge to reject a modeset. If
+ * this function passes all other callbacks must succeed for this
+ * configuration.
+ *
+ * NOTE:
+ *
+ * This function is called in the check phase of atomic modesets, which
+ * can be aborted for any reason (including on userspace's request to
+ * just check whether a configuration would be possible). Drivers MUST
+ * NOT touch any persistent state (hardware or software) or data
+ * structures except the passed in adjusted_mode parameter.
+ *
+ * RETURNS:
+ *
+ * True if an acceptable configuration is possible, false if the modeset
+ * operation should be rejected.
+ */
bool (*mode_fixup)(struct drm_bridge *bridge,
const struct drm_display_mode *mode,
struct drm_display_mode *adjusted_mode);
+ /**
+ * @disable:
+ *
+ * This callback should disable the bridge. It is called right before
+ * the preceding element in the display pipe is disabled. If the
+ * preceding element is a bridge this means it's called before that
+ * bridge's ->disable() function. If the preceding element is a
+ * &drm_encoder it's called right before the encoder's ->disable(),
+ * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
+ *
+ * The bridge can assume that the display pipe (i.e. clocks and timing
+ * signals) feeding it is still running when this callback is called.
+ */
void (*disable)(struct drm_bridge *bridge);
+
+ /**
+ * @post_disable:
+ *
+ * This callback should disable the bridge. It is called right after
+ * the preceding element in the display pipe is disabled. If the
+ * preceding element is a bridge this means it's called after that
+ * bridge's ->post_disable() function. If the preceding element is a
+ * &drm_encoder it's called right after the encoder's ->disable(),
+ * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
+ *
+ * The bridge must assume that the display pipe (i.e. clocks and timing
+ * singals) feeding it is no longer running when this callback is
+ * called.
+ */
void (*post_disable)(struct drm_bridge *bridge);
+
+ /**
+ * @mode_set:
+ *
+ * This callback should set the given mode on the bridge. It is called
+ * after the ->mode_set() callback for the preceding element in the
+ * display pipeline has been called already. The display pipe (i.e.
+ * clocks and timing signals) is off when this function is called.
+ */
void (*mode_set)(struct drm_bridge *bridge,
struct drm_display_mode *mode,
struct drm_display_mode *adjusted_mode);
+ /**
+ * @pre_enable:
+ *
+ * This callback should enable the bridge. It is called right before
+ * the preceding element in the display pipe is enabled. If the
+ * preceding element is a bridge this means it's called before that
+ * bridge's ->pre_enable() function. If the preceding element is a
+ * &drm_encoder it's called right before the encoder's ->enable(),
+ * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
+ *
+ * The display pipe (i.e. clocks and timing signals) feeding this bridge
+ * will not yet be running when this callback is called. The bridge must
+ * not enable the display link feeding the next bridge in the chain (if
+ * there is one) when this callback is called.
+ */
void (*pre_enable)(struct drm_bridge *bridge);
+
+ /**
+ * @enable:
+ *
+ * This callback should enable the bridge. It is called right after
+ * the preceding element in the display pipe is enabled. If the
+ * preceding element is a bridge this means it's called after that
+ * bridge's ->enable() function. If the preceding element is a
+ * &drm_encoder it's called right after the encoder's ->enable(),
+ * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
+ *
+ * The bridge can assume that the display pipe (i.e. clocks and timing
+ * signals) feeding it is running when this callback is called. This
+ * callback must enable the display link feeding the next bridge in the
+ * chain if there is one.
+ */
void (*enable)(struct drm_bridge *bridge);
};