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.
Reword both comments to better describe the legacy use cases where a shared lock was needed.
Signed-off-by: Maíra Canal mcanal@igalia.com
---
v1 -> v2: https://lore.kernel.org/dri-devel/20260411185756.1887119-4-mcanal@igalia.com...
- Be more explicit about not allowing new users to use an external lock. - De-duplicate the explanation in dma_fence_init64() by pointing to the dma_fence_init() documentation.
v2 -> v3: https://lore.kernel.org/dri-devel/20260419134943.54833-2-mcanal@igalia.com/T...
- Apply Christian's suggestion with small readability improvements.
--- drivers/dma-buf/dma-fence.c | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)
diff --git a/drivers/dma-buf/dma-fence.c b/drivers/dma-buf/dma-fence.c index b3bfa6943a8e..c7ea1e75d38a 100644 --- a/drivers/dma-buf/dma-fence.c +++ b/drivers/dma-buf/dma-fence.c @@ -1102,9 +1102,12 @@ __dma_fence_init(struct dma_fence *fence, const struct dma_fence_ops *ops, * context and seqno are used for easy comparison between fences, allowing * 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. + * External locks are a relic of legacy use cases that needed a shared lock + * to serialize signaling when no out-of-order signaling was possible through + * &dma_fence_ops.signaled. Drivers have abandoned this concept since the + * introduction of the callback, but the external lock is still around. New + * users MUST NOT use external locks, as they force the issuer to outlive all + * fences that reference the lock. */ void dma_fence_init(struct dma_fence *fence, const struct dma_fence_ops *ops, @@ -1129,9 +1132,8 @@ EXPORT_SYMBOL(dma_fence_init); * Context and seqno are used for easy comparison between fences, allowing * 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. + * New users MUST NOT use external locks. Check the documentation in + * dma_fence_init() to understand the motives behind the legacy use cases. */ void dma_fence_init64(struct dma_fence *fence, const struct dma_fence_ops *ops,
On 5/31/26 14:49, Maíra Canal wrote:
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.
Reword both comments to better describe the legacy use cases where a shared lock was needed.
Signed-off-by: Maíra Canal mcanal@igalia.com
Reviewed-by: Christian König christian.koenig@amd.com
I'm going to push this to drm-misc-next.
Thanks, Christian.
v1 -> v2: https://lore.kernel.org/dri-devel/20260411185756.1887119-4-mcanal@igalia.com...
- Be more explicit about not allowing new users to use an external lock.
- De-duplicate the explanation in dma_fence_init64() by pointing to the dma_fence_init() documentation.
v2 -> v3: https://lore.kernel.org/dri-devel/20260419134943.54833-2-mcanal@igalia.com/T...
- Apply Christian's suggestion with small readability improvements.
drivers/dma-buf/dma-fence.c | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)
diff --git a/drivers/dma-buf/dma-fence.c b/drivers/dma-buf/dma-fence.c index b3bfa6943a8e..c7ea1e75d38a 100644 --- a/drivers/dma-buf/dma-fence.c +++ b/drivers/dma-buf/dma-fence.c @@ -1102,9 +1102,12 @@ __dma_fence_init(struct dma_fence *fence, const struct dma_fence_ops *ops,
- context and seqno are used for easy comparison between fences, allowing
- 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.
- External locks are a relic of legacy use cases that needed a shared lock
- to serialize signaling when no out-of-order signaling was possible through
- &dma_fence_ops.signaled. Drivers have abandoned this concept since the
- introduction of the callback, but the external lock is still around. New
- users MUST NOT use external locks, as they force the issuer to outlive all
*/
- fences that reference the lock.
void dma_fence_init(struct dma_fence *fence, const struct dma_fence_ops *ops, @@ -1129,9 +1132,8 @@ EXPORT_SYMBOL(dma_fence_init);
- Context and seqno are used for easy comparison between fences, allowing
- 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.
- New users MUST NOT use external locks. Check the documentation in
*/
- dma_fence_init() to understand the motives behind the legacy use cases.
void dma_fence_init64(struct dma_fence *fence, const struct dma_fence_ops *ops,
linaro-mm-sig@lists.linaro.org
-
Christian König -
Maíra Canal