[PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation

[Daniel Vetter]

On Wed, Jul 21, 2021 at 11:21:32AM +0200, Christian König wrote:
> This callback is pretty much deprecated and should not be used by new implementations.
> 
> Clarify that in the documentation as well.
> 
> Signed-off-by: Christian König <christian.koenig at amd.com>
> ---
>  include/linux/dma-fence.h | 10 +++-------
>  1 file changed, 3 insertions(+), 7 deletions(-)
> 
> diff --git a/include/linux/dma-fence.h b/include/linux/dma-fence.h
> index 6ffb4b2c6371..a44e42b86c2a 100644
> --- a/include/linux/dma-fence.h
> +++ b/include/linux/dma-fence.h
> @@ -214,19 +214,15 @@ struct dma_fence_ops {
>  	 * Custom wait implementation, defaults to dma_fence_default_wait() if
>  	 * not set.
>  	 *
> -	 * The dma_fence_default_wait implementation should work for any fence, as long
> -	 * as @enable_signaling works correctly. This hook allows drivers to
> -	 * have an optimized version for the case where a process context is
> -	 * already available, e.g. if @enable_signaling for the general case
> -	 * needs to set up a worker thread.
> +	 * Deprecated and should not be used by new implementations. Only used
> +	 * by existing implementations which need special handling for their
> +	 * hardware reset procedure.

I thought the other reason was unreliable interrupts, so waiters had to
wake up once per jiffy? So maybe: "... for their hw reset procedure or for
handling missed interrupts".

Maybe also add here:

New implementations must have an @enable_signalling and dma_fence_signal()
implementation which does not require special handling to make
dma_fence_wait() work.

With these:

Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>

>  	 *
>  	 * Must return -ERESTARTSYS if the wait is intr = true and the wait was
>  	 * interrupted, and remaining jiffies if fence has signaled, or 0 if wait
>  	 * timed out. Can also return other error values on custom implementations,
>  	 * which should be treated as if the fence is signaled. For example a hardware
>  	 * lockup could be reported like that.
> -	 *
> -	 * This callback is optional.
>  	 */
>  	signed long (*wait)(struct dma_fence *fence,
>  			    bool intr, signed long timeout);
> -- 
> 2.25.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch