[PATCH] dma-fence: Clarify external lock use case in dma_fence_init() docs

[Maíra Canal <mcanal@igalia.com>]

The kerneldoc comment on dma_fence_init() and dma_fence_init64() describe
the legacy reason to pass an external lock as a need to prevent multiple
fences "from signaling out of order". However, this wording is a bit
misleading: a shared spinlock does not (and cannot) prevent the signaler
from signaling out of order. Signaling order is the driver's responsibility
regardless of whether the lock is shared or per-fence.

What a shared lock actually provides is serialization of signaling and
observation across fences in a given context, so that observers never
see a later fence signaled while an earlier one is not.

Reword both comments to describe this more accurately.

Signed-off-by: Maíra Canal <mcanal@igalia.com>
---

Hi,

While reading the documentation, I found this particular paragraph quite
hard to understand. As I understand it, locks don't enforce order, only
serialization, but the paragraph seems to communicate the other way around.
Due to that, I had the impression that the current wording can be
misleading for driver developers.

I'm proposing a new wording to better describe the use case of the
external lock based on my understanding, but it would be great to hear
the feedback and suggestions from more experienced developers who might
have more insight about these legacy use cases.

Best regards,
- Maíra

 drivers/dma-buf/dma-fence.c | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/drivers/dma-buf/dma-fence.c b/drivers/dma-buf/dma-fence.c
index 1826ba73094c..bdc29d1c1b5c 100644
--- a/drivers/dma-buf/dma-fence.c
+++ b/drivers/dma-buf/dma-fence.c
@@ -1102,8 +1102,10 @@ __dma_fence_init(struct dma_fence *fence, const struct dma_fence_ops *ops,
  * to check which fence is later by simply using dma_fence_later().
  *
  * It is strongly discouraged to provide an external lock because this couples
- * lock and fence life time. This is only allowed for legacy use cases when
- * multiple fences need to be prevented from signaling out of order.
+ * lock and fence lifetime. This is only allowed for legacy use cases that need
+ * a shared lock to serialize signaling and observation of fences within a
+ * context, so that observers never see a later fence signaled while an earlier
+ * one isn't.
  */
 void
 dma_fence_init(struct dma_fence *fence, const struct dma_fence_ops *ops,
@@ -1129,8 +1131,10 @@ EXPORT_SYMBOL(dma_fence_init);
  * to check which fence is later by simply using dma_fence_later().
  *
  * It is strongly discouraged to provide an external lock because this couples
- * lock and fence life time. This is only allowed for legacy use cases when
- * multiple fences need to be prevented from signaling out of order.
+ * lock and fence lifetime. This is only allowed for legacy use cases that need
+ * a shared lock to serialize signaling and observation of fences within a
+ * context, so that observers never see a later fence signaled while an earlier
+ * one isn't.
  */
 void
 dma_fence_init64(struct dma_fence *fence, const struct dma_fence_ops *ops,
-- 
2.53.0