[PATCH v3 10/21] drm/bridge: Clarify the atomic enable/disable hooks semantics

[Neil Armstrong]

On 23/10/2019 17:45, Boris Brezillon wrote:
> The [pre_]enable/[post_]disable hooks are passed the old atomic state.
> Update the doc and rename the arguments to make it clear.
> 
> Signed-off-by: Boris Brezillon <boris.brezillon at collabora.com>
> ---
> Changes in v3:
> * New patch
> ---
>  drivers/gpu/drm/drm_bridge.c | 24 ++++++++++++------------
>  include/drm/drm_bridge.h     | 16 ++++++++++++----
>  2 files changed, 24 insertions(+), 16 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index c53966767782..ca74bfe028c9 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -447,7 +447,7 @@ EXPORT_SYMBOL(drm_bridge_chain_enable);
>  /**
>   * drm_atomic_bridge_chain_disable - disables all bridges in the encoder chain
>   * @bridge: bridge control structure
> - * @state: atomic state being committed
> + * @old_state: old atomic state
>   *
>   * Calls &drm_bridge_funcs.atomic_disable (falls back on
>   * &drm_bridge_funcs.disable) op for all the bridges in the encoder chain,
> @@ -457,7 +457,7 @@ EXPORT_SYMBOL(drm_bridge_chain_enable);
>   * Note: the bridge passed should be the one closest to the encoder
>   */
>  void drm_atomic_bridge_chain_disable(struct drm_bridge *bridge,
> -				     struct drm_atomic_state *state)
> +				     struct drm_atomic_state *old_state)
>  {
>  	struct drm_encoder *encoder;
>  	struct drm_bridge *iter;
> @@ -469,7 +469,7 @@ void drm_atomic_bridge_chain_disable(struct drm_bridge *bridge,
>  	list_for_each_entry_reverse(iter, &encoder->bridge_chain,
>  				    chain_node) {
>  		if (iter->funcs->atomic_disable)
> -			iter->funcs->atomic_disable(iter, state);
> +			iter->funcs->atomic_disable(iter, old_state);
>  		else if (iter->funcs->disable)
>  			iter->funcs->disable(iter);
>  
> @@ -483,7 +483,7 @@ EXPORT_SYMBOL(drm_atomic_bridge_chain_disable);
>   * drm_atomic_bridge_chain_post_disable - cleans up after disabling all bridges
>   *					  in the encoder chain
>   * @bridge: bridge control structure
> - * @state: atomic state being committed
> + * @old_state: old atomic state
>   *
>   * Calls &drm_bridge_funcs.atomic_post_disable (falls back on
>   * &drm_bridge_funcs.post_disable) op for all the bridges in the encoder chain,
> @@ -493,7 +493,7 @@ EXPORT_SYMBOL(drm_atomic_bridge_chain_disable);
>   * Note: the bridge passed should be the one closest to the encoder
>   */
>  void drm_atomic_bridge_chain_post_disable(struct drm_bridge *bridge,
> -					  struct drm_atomic_state *state)
> +					  struct drm_atomic_state *old_state)
>  {
>  	struct drm_encoder *encoder;
>  
> @@ -504,7 +504,7 @@ void drm_atomic_bridge_chain_post_disable(struct drm_bridge *bridge,
>  	list_for_each_entry_from(bridge, &encoder->bridge_chain,
>  				 chain_node) {
>  		if (bridge->funcs->atomic_post_disable)
> -			bridge->funcs->atomic_post_disable(bridge, state);
> +			bridge->funcs->atomic_post_disable(bridge, old_state);
>  		else if (bridge->funcs->post_disable)
>  			bridge->funcs->post_disable(bridge);
>  	}
> @@ -515,7 +515,7 @@ EXPORT_SYMBOL(drm_atomic_bridge_chain_post_disable);
>   * drm_atomic_bridge_chain_pre_enable - prepares for enabling all bridges in
>   *					the encoder chain
>   * @bridge: bridge control structure
> - * @state: atomic state being committed
> + * @old_state: old atomic state
>   *
>   * Calls &drm_bridge_funcs.atomic_pre_enable (falls back on
>   * &drm_bridge_funcs.pre_enable) op for all the bridges in the encoder chain,
> @@ -525,7 +525,7 @@ EXPORT_SYMBOL(drm_atomic_bridge_chain_post_disable);
>   * Note: the bridge passed should be the one closest to the encoder
>   */
>  void drm_atomic_bridge_chain_pre_enable(struct drm_bridge *bridge,
> -					struct drm_atomic_state *state)
> +					struct drm_atomic_state *old_state)
>  {
>  	struct drm_encoder *encoder;
>  	struct drm_bridge *iter;
> @@ -537,7 +537,7 @@ void drm_atomic_bridge_chain_pre_enable(struct drm_bridge *bridge,
>  	list_for_each_entry_reverse(iter, &bridge->encoder->bridge_chain,
>  				    chain_node) {
>  		if (iter->funcs->atomic_pre_enable)
> -			iter->funcs->atomic_pre_enable(iter, state);
> +			iter->funcs->atomic_pre_enable(iter, old_state);
>  		else if (iter->funcs->pre_enable)
>  			iter->funcs->pre_enable(iter);
>  
> @@ -550,7 +550,7 @@ EXPORT_SYMBOL(drm_atomic_bridge_chain_pre_enable);
>  /**
>   * drm_atomic_bridge_chain_enable - enables all bridges in the encoder chain
>   * @bridge: bridge control structure
> - * @state: atomic state being committed
> + * @old_state: old atomic state
>   *
>   * Calls &drm_bridge_funcs.atomic_enable (falls back on
>   * &drm_bridge_funcs.enable) op for all the bridges in the encoder chain,
> @@ -560,7 +560,7 @@ EXPORT_SYMBOL(drm_atomic_bridge_chain_pre_enable);
>   * Note: the bridge passed should be the one closest to the encoder
>   */
>  void drm_atomic_bridge_chain_enable(struct drm_bridge *bridge,
> -				    struct drm_atomic_state *state)
> +				    struct drm_atomic_state *old_state)
>  {
>  	struct drm_encoder *encoder;
>  
> @@ -571,7 +571,7 @@ void drm_atomic_bridge_chain_enable(struct drm_bridge *bridge,
>  	list_for_each_entry_from(bridge, &bridge->encoder->bridge_chain,
>  				 chain_node) {
>  		if (bridge->funcs->atomic_enable)
> -			bridge->funcs->atomic_enable(bridge, state);
> +			bridge->funcs->atomic_enable(bridge, old_state);
>  		else if (bridge->funcs->enable)
>  			bridge->funcs->enable(bridge);
>  	}
> diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
> index a608c47d1de5..e814e6d6e7c2 100644
> --- a/include/drm/drm_bridge.h
> +++ b/include/drm/drm_bridge.h
> @@ -266,6 +266,8 @@ struct drm_bridge_funcs {
>  	 * bridge's @atomic_pre_enable or @pre_enable function. If the preceding
>  	 * element is a &drm_encoder it's called right before the encoder's
>  	 * &drm_encoder_helper_funcs.atomic_enable hook.
> +	 * This hook is passed the old atomic state (atomic state after new/old
> +	 * states have been swapped).
>  	 *
>  	 * 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
> @@ -281,7 +283,7 @@ struct drm_bridge_funcs {
>  	 * The @atomic_pre_enable callback is optional.
>  	 */
>  	void (*atomic_pre_enable)(struct drm_bridge *bridge,
> -				  struct drm_atomic_state *state);
> +				  struct drm_atomic_state *old_state);
>  
>  	/**
>  	 * @atomic_enable:
> @@ -292,6 +294,8 @@ struct drm_bridge_funcs {
>  	 * bridge's @atomic_enable or @enable function. If the preceding element
>  	 * is a &drm_encoder it's called right after the encoder's
>  	 * &drm_encoder_helper_funcs.atomic_enable hook.
> +	 * This hook is passed the old atomic state (atomic state after new/old
> +	 * states have been swapped).
>  	 *
>  	 * The bridge can assume that the display pipe (i.e. clocks and timing
>  	 * signals) feeding it is running when this callback is called. This
> @@ -306,7 +310,7 @@ struct drm_bridge_funcs {
>  	 * The @atomic_enable callback is optional.
>  	 */
>  	void (*atomic_enable)(struct drm_bridge *bridge,
> -			      struct drm_atomic_state *state);
> +			      struct drm_atomic_state *old_state);
>  	/**
>  	 * @atomic_disable:
>  	 *
> @@ -316,6 +320,8 @@ struct drm_bridge_funcs {
>  	 * bridge's @atomic_disable or @disable vfunc. If the preceding element
>  	 * is a &drm_encoder it's called right before the
>  	 * &drm_encoder_helper_funcs.atomic_disable hook.
> +	 * This hook is passed the old atomic state (atomic state after new/old
> +	 * states have been swapped).
>  	 *
>  	 * The bridge can assume that the display pipe (i.e. clocks and timing
>  	 * signals) feeding it is still running when this callback is called.
> @@ -329,7 +335,7 @@ struct drm_bridge_funcs {
>  	 * The @atomic_disable callback is optional.
>  	 */
>  	void (*atomic_disable)(struct drm_bridge *bridge,
> -			       struct drm_atomic_state *state);
> +			       struct drm_atomic_state *old_state);
>  
>  	/**
>  	 * @atomic_post_disable:
> @@ -340,6 +346,8 @@ struct drm_bridge_funcs {
>  	 * @atomic_post_disable or @post_disable function. If the preceding
>  	 * element is a &drm_encoder it's called right after the encoder's
>  	 * &drm_encoder_helper_funcs.atomic_disable hook.
> +	 * This hook is passed the old atomic state (atomic state after new/old
> +	 * states have been swapped).
>  	 *
>  	 * The bridge must assume that the display pipe (i.e. clocks and timing
>  	 * signals) feeding it is no longer running when this callback is
> @@ -355,7 +363,7 @@ struct drm_bridge_funcs {
>  	 * The @atomic_post_disable callback is optional.
>  	 */
>  	void (*atomic_post_disable)(struct drm_bridge *bridge,
> -				    struct drm_atomic_state *state);
> +				    struct drm_atomic_state *old_state);
>  
>  	/**
>  	 * @atomic_duplicate_state:
> 

Reviewed-by: Neil Armstrong <narmstrong at baylibre.com>