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

[Daniel Vetter]

On Fri, Jun 26, 2020 at 2:21 PM Lionel Landwerlin
<lionel.g.landwerlin at intel.com> wrote:
>
> Trying to explain a bit how this thing works. In my opinion diagrams
> are a bit easier to understand than words.

kerneldoc supports in-line DOT graphs, see e.g.

https://dri.freedesktop.org/docs/drm/gpu/drm-kms.html#overview

If that doesn't work, then you can include a full-blown svg too.

And yes for this a quick DOT graph that explains how things connect
sound like the perfect use of a diagramm.

Cheers, Daniel

>
> 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.
> + *
> + * One can also traverse the chain's linked list to find a &struct
> + * dma_fence_chain that when signaled guarantees that all previous fences in
> + * the chain are signaled. dma_fence_chain_find_seqno() provides this
> + * functionality.
> + */
> +
>  static bool dma_fence_chain_enable_signaling(struct dma_fence *fence);
>
>  /**
> --
> 2.27.0
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel



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