[PATCH v7 05/54] drm/bridge: Fix atomic state ops documentation

[Boris Brezillon]

On Sat, 22 Feb 2020 17:00:17 +0200
Laurent Pinchart <laurent.pinchart at ideasonboard.com> wrote:

> The drm_bridge_funcs atomic_state_duplicate and atomic_state_destroy
> operations are erroneously documented as having a default implementation
> if not implemented in bridge drivers. This isn't correct, fix the
> documentation.

Oops, looks like a leftover from a previous version. Thanks for fixing
that.

Reviewed-by: Boris Brezillon <boris.brezillon at collabora.com>

> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> ---
>  include/drm/drm_bridge.h | 20 ++++++++++++++------
>  1 file changed, 14 insertions(+), 6 deletions(-)
> 
> diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
> index 999faaaab9a1..38de129d5947 100644
> --- a/include/drm/drm_bridge.h
> +++ b/include/drm/drm_bridge.h
> @@ -349,9 +349,11 @@ struct drm_bridge_funcs {
>  	 * Duplicate the current bridge state object (which is guaranteed to be
>  	 * non-NULL).
>  	 *
> -	 * The atomic_duplicate_state() hook is optional. When not implemented
> -	 * the core allocates a drm_bridge_state object and calls
> -	 * __drm_atomic_helper_bridge_duplicate_state() to initialize it.
> +	 * The atomic_duplicate_state hook is mandatory if the bridge
> +	 * implements any of the atomic hooks, and should be left unassigned
> +	 * otherwise. For bridges that don't subclass &drm_bridge_state, the
> +	 * drm_atomic_helper_bridge_duplicate_state() helper function shall be
> +	 * used to implement this hook.
>  	 *
>  	 * RETURNS:
>  	 * A valid drm_bridge_state object or NULL if the allocation fails.
> @@ -364,8 +366,11 @@ struct drm_bridge_funcs {
>  	 * Destroy a bridge state object previously allocated by
>  	 * &drm_bridge_funcs.atomic_duplicate_state().
>  	 *
> -	 * The atomic_destroy_state hook is optional. When not implemented the
> -	 * core calls kfree() on the state.
> +	 * The atomic_destroy_state hook is mandatory if the bridge implements
> +	 * any of the atomic hooks, and should be left unassigned otherwise.
> +	 * For bridges that don't subclass &drm_bridge_state, the
> +	 * drm_atomic_helper_bridge_destroy_state() helper function shall be
> +	 * used to implement this hook.
>  	 */
>  	void (*atomic_destroy_state)(struct drm_bridge *bridge,
>  				     struct drm_bridge_state *state);
> @@ -474,7 +479,10 @@ struct drm_bridge_funcs {
>  	 * This function is called at attach time.
>  	 *
>  	 * The atomic_reset hook is mandatory if the bridge implements any of
> -	 * the atomic hooks, and should be left unassigned otherwise.
> +	 * the atomic hooks, and should be left unassigned otherwise. For
> +	 * bridges that don't subclass &drm_bridge_state, the
> +	 * drm_atomic_helper_bridge_reset() helper function shall be used to
> +	 * implement this hook.
>  	 *
>  	 * Note that the atomic_reset() semantics is not exactly matching the
>  	 * reset() semantics found on other components (connector, plane, ...).