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

[Lionel Landwerlin]

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.
+ *
+ * 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