* Harden the dma-fence documentation a bit more @ 2021-09-01 12:02 Christian König 2021-09-01 12:02 ` [PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation Christian König 2021-09-01 12:02 ` [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation Christian König 0 siblings, 2 replies; 6+ messages in thread From: Christian König @ 2021-09-01 12:02 UTC (permalink / raw) To: dri-devel; +Cc: daniel, linux-media, linaro-mm-sig Hi guys, while it is in most cases technically possible to not have a reference to the dma_fence when adding a callback it is usually a good idea to make sure to always have a reference anyway. Otherwise we can indeed see cases where this doesn't really work as intended like for example in the now fixed EPOLL code. Regards, Christian. ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation 2021-09-01 12:02 Harden the dma-fence documentation a bit more Christian König @ 2021-09-01 12:02 ` Christian König 2021-09-02 14:37 ` Daniel Vetter 2021-09-01 12:02 ` [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation Christian König 1 sibling, 1 reply; 6+ messages in thread From: Christian König @ 2021-09-01 12:02 UTC (permalink / raw) To: dri-devel; +Cc: daniel, linux-media, linaro-mm-sig This callback is pretty much deprecated and should not be used by new implementations. Clarify that in the documentation as well. Signed-off-by: Christian König <christian.koenig@amd.com> --- include/linux/dma-fence.h | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/include/linux/dma-fence.h b/include/linux/dma-fence.h index 6ffb4b2c6371..a44e42b86c2a 100644 --- a/include/linux/dma-fence.h +++ b/include/linux/dma-fence.h @@ -214,19 +214,15 @@ struct dma_fence_ops { * Custom wait implementation, defaults to dma_fence_default_wait() if * not set. * - * The dma_fence_default_wait implementation should work for any fence, as long - * as @enable_signaling works correctly. This hook allows drivers to - * have an optimized version for the case where a process context is - * already available, e.g. if @enable_signaling for the general case - * needs to set up a worker thread. + * Deprecated and should not be used by new implementations. Only used + * by existing implementations which need special handling for their + * hardware reset procedure. * * Must return -ERESTARTSYS if the wait is intr = true and the wait was * interrupted, and remaining jiffies if fence has signaled, or 0 if wait * timed out. Can also return other error values on custom implementations, * which should be treated as if the fence is signaled. For example a hardware * lockup could be reported like that. - * - * This callback is optional. */ signed long (*wait)(struct dma_fence *fence, bool intr, signed long timeout); -- 2.25.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation 2021-09-01 12:02 ` [PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation Christian König @ 2021-09-02 14:37 ` Daniel Vetter 0 siblings, 0 replies; 6+ messages in thread From: Daniel Vetter @ 2021-09-02 14:37 UTC (permalink / raw) To: Christian König; +Cc: dri-devel, daniel, linux-media, linaro-mm-sig On Wed, Sep 01, 2021 at 02:02:39PM +0200, Christian König wrote: > This callback is pretty much deprecated and should not be used by new implementations. > > Clarify that in the documentation as well. > > Signed-off-by: Christian König <christian.koenig@amd.com> Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> > --- > include/linux/dma-fence.h | 10 +++------- > 1 file changed, 3 insertions(+), 7 deletions(-) > > diff --git a/include/linux/dma-fence.h b/include/linux/dma-fence.h > index 6ffb4b2c6371..a44e42b86c2a 100644 > --- a/include/linux/dma-fence.h > +++ b/include/linux/dma-fence.h > @@ -214,19 +214,15 @@ struct dma_fence_ops { > * Custom wait implementation, defaults to dma_fence_default_wait() if > * not set. > * > - * The dma_fence_default_wait implementation should work for any fence, as long > - * as @enable_signaling works correctly. This hook allows drivers to > - * have an optimized version for the case where a process context is > - * already available, e.g. if @enable_signaling for the general case > - * needs to set up a worker thread. > + * Deprecated and should not be used by new implementations. Only used > + * by existing implementations which need special handling for their > + * hardware reset procedure. > * > * Must return -ERESTARTSYS if the wait is intr = true and the wait was > * interrupted, and remaining jiffies if fence has signaled, or 0 if wait > * timed out. Can also return other error values on custom implementations, > * which should be treated as if the fence is signaled. For example a hardware > * lockup could be reported like that. > - * > - * This callback is optional. > */ > signed long (*wait)(struct dma_fence *fence, > bool intr, signed long timeout); > -- > 2.25.1 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation 2021-09-01 12:02 Harden the dma-fence documentation a bit more Christian König 2021-09-01 12:02 ` [PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation Christian König @ 2021-09-01 12:02 ` Christian König 2021-09-02 14:42 ` Daniel Vetter 1 sibling, 1 reply; 6+ messages in thread From: Christian König @ 2021-09-01 12:02 UTC (permalink / raw) To: dri-devel; +Cc: daniel, linux-media, linaro-mm-sig That the caller doesn't need to keep a reference is rather risky and not defensive at all. Especially dma_buf_poll got that horrible wrong, so better remove that sentence and also clarify that the callback might be called in atomic or interrupt context. Signed-off-by: Christian König <christian.koenig@amd.com> --- drivers/dma-buf/dma-fence.c | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/drivers/dma-buf/dma-fence.c b/drivers/dma-buf/dma-fence.c index ce0f5eff575d..1e82ecd443fa 100644 --- a/drivers/dma-buf/dma-fence.c +++ b/drivers/dma-buf/dma-fence.c @@ -616,20 +616,17 @@ EXPORT_SYMBOL(dma_fence_enable_sw_signaling); * @cb: the callback to register * @func: the function to call * + * Add a software callback to the fence. The caller should keep a reference to + * the fence. + * * @cb will be initialized by dma_fence_add_callback(), no initialization * by the caller is required. Any number of callbacks can be registered * to a fence, but a callback can only be registered to one fence at a time. * - * Note that the callback can be called from an atomic context. If - * fence is already signaled, this function will return -ENOENT (and + * If fence is already signaled, this function will return -ENOENT (and * *not* call the callback). * - * Add a software callback to the fence. Same restrictions apply to - * refcount as it does to dma_fence_wait(), however the caller doesn't need to - * keep a refcount to fence afterward dma_fence_add_callback() has returned: - * when software access is enabled, the creator of the fence is required to keep - * the fence alive until after it signals with dma_fence_signal(). The callback - * itself can be called from irq context. + * Note that the callback can be called from an atomic context or irq context. * * Returns 0 in case of success, -ENOENT if the fence is already signaled * and -EINVAL in case of error. -- 2.25.1 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation 2021-09-01 12:02 ` [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation Christian König @ 2021-09-02 14:42 ` Daniel Vetter 2021-09-03 8:22 ` Christian König 0 siblings, 1 reply; 6+ messages in thread From: Daniel Vetter @ 2021-09-02 14:42 UTC (permalink / raw) To: Christian König; +Cc: dri-devel, daniel, linux-media, linaro-mm-sig On Wed, Sep 01, 2021 at 02:02:40PM +0200, Christian König wrote: > That the caller doesn't need to keep a reference is rather > risky and not defensive at all. > > Especially dma_buf_poll got that horrible wrong, so better > remove that sentence and also clarify that the callback > might be called in atomic or interrupt context. > > Signed-off-by: Christian König <christian.koenig@amd.com> Still on the fence between documenting the precise rules and documenting the safe rules, but this is tricky enough that you got me convinced. Plus shorter, simpler, clearer kerneldoc has much better chances of being read, understood and followed. Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> > --- > drivers/dma-buf/dma-fence.c | 13 +++++-------- > 1 file changed, 5 insertions(+), 8 deletions(-) > > diff --git a/drivers/dma-buf/dma-fence.c b/drivers/dma-buf/dma-fence.c > index ce0f5eff575d..1e82ecd443fa 100644 > --- a/drivers/dma-buf/dma-fence.c > +++ b/drivers/dma-buf/dma-fence.c > @@ -616,20 +616,17 @@ EXPORT_SYMBOL(dma_fence_enable_sw_signaling); > * @cb: the callback to register > * @func: the function to call > * > + * Add a software callback to the fence. The caller should keep a reference to > + * the fence. > + * > * @cb will be initialized by dma_fence_add_callback(), no initialization > * by the caller is required. Any number of callbacks can be registered > * to a fence, but a callback can only be registered to one fence at a time. > * > - * Note that the callback can be called from an atomic context. If > - * fence is already signaled, this function will return -ENOENT (and > + * If fence is already signaled, this function will return -ENOENT (and > * *not* call the callback). > * > - * Add a software callback to the fence. Same restrictions apply to > - * refcount as it does to dma_fence_wait(), however the caller doesn't need to > - * keep a refcount to fence afterward dma_fence_add_callback() has returned: > - * when software access is enabled, the creator of the fence is required to keep > - * the fence alive until after it signals with dma_fence_signal(). The callback > - * itself can be called from irq context. > + * Note that the callback can be called from an atomic context or irq context. > * > * Returns 0 in case of success, -ENOENT if the fence is already signaled > * and -EINVAL in case of error. > -- > 2.25.1 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation 2021-09-02 14:42 ` Daniel Vetter @ 2021-09-03 8:22 ` Christian König 0 siblings, 0 replies; 6+ messages in thread From: Christian König @ 2021-09-03 8:22 UTC (permalink / raw) To: Daniel Vetter; +Cc: dri-devel, linux-media, linaro-mm-sig Am 02.09.21 um 16:42 schrieb Daniel Vetter: > On Wed, Sep 01, 2021 at 02:02:40PM +0200, Christian König wrote: >> That the caller doesn't need to keep a reference is rather >> risky and not defensive at all. >> >> Especially dma_buf_poll got that horrible wrong, so better >> remove that sentence and also clarify that the callback >> might be called in atomic or interrupt context. >> >> Signed-off-by: Christian König <christian.koenig@amd.com> > Still on the fence between documenting the precise rules and documenting > the safe rules, but this is tricky enough that you got me convinced. Plus > shorter, simpler, clearer kerneldoc has much better chances of being read, > understood and followed. I think that for documentation we should apply the same rules we have for code. E.g. keep it simple until you absolutely have to make it complex and keep it defensive with the least probability for something to go wrong. > Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch> Thanks, Christian. > >> --- >> drivers/dma-buf/dma-fence.c | 13 +++++-------- >> 1 file changed, 5 insertions(+), 8 deletions(-) >> >> diff --git a/drivers/dma-buf/dma-fence.c b/drivers/dma-buf/dma-fence.c >> index ce0f5eff575d..1e82ecd443fa 100644 >> --- a/drivers/dma-buf/dma-fence.c >> +++ b/drivers/dma-buf/dma-fence.c >> @@ -616,20 +616,17 @@ EXPORT_SYMBOL(dma_fence_enable_sw_signaling); >> * @cb: the callback to register >> * @func: the function to call >> * >> + * Add a software callback to the fence. The caller should keep a reference to >> + * the fence. >> + * >> * @cb will be initialized by dma_fence_add_callback(), no initialization >> * by the caller is required. Any number of callbacks can be registered >> * to a fence, but a callback can only be registered to one fence at a time. >> * >> - * Note that the callback can be called from an atomic context. If >> - * fence is already signaled, this function will return -ENOENT (and >> + * If fence is already signaled, this function will return -ENOENT (and >> * *not* call the callback). >> * >> - * Add a software callback to the fence. Same restrictions apply to >> - * refcount as it does to dma_fence_wait(), however the caller doesn't need to >> - * keep a refcount to fence afterward dma_fence_add_callback() has returned: >> - * when software access is enabled, the creator of the fence is required to keep >> - * the fence alive until after it signals with dma_fence_signal(). The callback >> - * itself can be called from irq context. >> + * Note that the callback can be called from an atomic context or irq context. >> * >> * Returns 0 in case of success, -ENOENT if the fence is already signaled >> * and -EINVAL in case of error. >> -- >> 2.25.1 >> ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2021-09-03 8:22 UTC | newest] Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2021-09-01 12:02 Harden the dma-fence documentation a bit more Christian König 2021-09-01 12:02 ` [PATCH 1/2] dma-buf: clarify dma_fence_ops->wait documentation Christian König 2021-09-02 14:37 ` Daniel Vetter 2021-09-01 12:02 ` [PATCH 2/2] dma-buf: clarify dma_fence_add_callback documentation Christian König 2021-09-02 14:42 ` Daniel Vetter 2021-09-03 8:22 ` Christian König
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.