[PATCH] dma-buf: document dma-fence-chain purpose/behavior

[Chris Wilson]

Quoting Lionel Landwerlin (2020-06-26 13:21:00)
> Trying to explain a bit how this thing works. In my opinion diagrams
> are a bit easier to understand than words.
> 
> Signed-off-by: Lionel Landwerlin <lionel.g.landwerlin at intel.com>
> ---
>  drivers/dma-buf/dma-fence-chain.c | 37 +++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/drivers/dma-buf/dma-fence-chain.c b/drivers/dma-buf/dma-fence-chain.c
> index 3d123502ff12..ac90ddf37b55 100644
> --- a/drivers/dma-buf/dma-fence-chain.c
> +++ b/drivers/dma-buf/dma-fence-chain.c
> @@ -9,6 +9,43 @@
>  
>  #include <linux/dma-fence-chain.h>
>  
> +/**
> + * DOC: DMA fence chains overview
> + *
> + * DMA fence chains, represented by &struct dma_fence_chain, are a kernel
> + * internal synchronization primitive providing a wrapping mechanism of other
> + * DMA fences in the form a single link list.
> + *
> + * One of the use case of this primitive is to implement Vulkan timeline
> + * semaphores (see VK_KHR_timeline_semaphore extension or Vulkan specification
> + * 1.2).
> + *
> + * Each DMA fence chain item wraps 2 items :
> + *
> + * - A previous DMA fence.
> + *
> + * - A DMA fence associated to the current &struct dma_fence_chain.
> + *
> + * A DMA fence chain becomes signaled when its previous fence as well as its
> + * associated fence are signaled. If a chain of dma fence chains is created,
> + * this property recurses, meaning that any dma fence chain element in the
> + * list becomes signaled only if its associated fence and all the previous
> + * fences in the chain are also signaled.
> + *
> + * A DMA fence chain's seqno is specified through dma_fence_chain_init(). This
> + * value is lower bound to the seqno of the previous fence to ensure the chain
> + * is monotically increasing.
> + *
> + * By traversing the chain's linked list, one can compute a seqno number
> + * associated with the chain such that is the highest number for which all
> + * previous fences have signaled.

Next fence - 1 == highest seqno for all previous fences.

Ok, what about the end point then? If you ask for a seqno higher than
the last fence. Since that is not yet defined, it is an error, right?
Otherwise, we could interpret the highest possible seqno for the last
fence as meaning U64_MAX.
-Chris