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 <[email protected]>
Reviewed-by: Christian König <[email protected]>
I'm going to push this to drm-misc-next.
Thanks,
Christian.
>
> ---
>
> v1 -> v2:
> https://lore.kernel.org/dri-devel/[email protected]/
>
> - 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/[email protected]/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,
