[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 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?


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