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

[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@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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [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@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@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@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel



-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

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

[Lionel Landwerlin]

On 26/06/2020 15:43, Daniel Vetter wrote:
> On Fri, Jun 26, 2020 at 2:21 PM Lionel Landwerlin
> <lionel.g.landwerlin@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

Thanks!

Though I'm thinking I need a few to show the signaling behavior.

Not sure how tractable that is with DOT/SVG.

My last attempt was a series of slides...


-Lionel

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [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@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
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

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

[Lionel Landwerlin]

On 26/06/2020 17:22, Chris Wilson wrote:
> 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@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?


Correct, find_seqno() will return -EINVAL in that case.


-Lionel


> Otherwise, we could interpret the highest possible seqno for the last
> fence as meaning U64_MAX.
> -Chris


_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel