| Message ID | 20200626122100.55123-1-lionel.g.landwerlin@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | dma-buf: document dma-fence-chain purpose/behavior | expand |
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
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
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
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
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); /**
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(+)