The current documentation of dma_fence_is_signaled() and dma_fence_is_signaled_locked() does not explicitly mention that those functions can signal the fence.
Furthermore, the documentation of the return value reads as if the returned boolean only describes whether dma_fence_signal() (or similar) had been called before this function call already. That's not the case, since dma_fence_ops.signaled() usually just checks through the sequence number whether the hardware is finished with a fence. That doesn't mean a signaling function has been called already. Make the documentation clearer. Move the Return: documentation to the end, since that's the officially recommended docu style. Signed-off-by: Philipp Stanner <pha...@kernel.org> --- include/linux/dma-fence.h | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/include/linux/dma-fence.h b/include/linux/dma-fence.h index e7ad819962e3..939df0ab3224 100644 --- a/include/linux/dma-fence.h +++ b/include/linux/dma-fence.h @@ -407,14 +407,21 @@ void dma_fence_enable_sw_signaling(struct dma_fence *fence); * is signaled yet. * @fence: the fence to check * - * Returns true if the fence was already signaled, false if not. Since this - * function doesn't enable signaling, it is not guaranteed to ever return - * true if dma_fence_add_callback(), dma_fence_wait() or + * Checks whether the fence was already signaled, and, if not, whether + * &struct dma_fence_ops.signaled indicates that it should be signaled. If so, + * the fence gets signaled here. + * + * Since this function doesn't enable signaling, it is not guaranteed to ever + * return true if dma_fence_add_callback(), dma_fence_wait() or * dma_fence_enable_sw_signaling() haven't been called before. * * This function requires &dma_fence.lock to be held. * * See also dma_fence_is_signaled(). + * + * Return: true if the fence was already signaled, or if + * &struct dma_fence_ops.signaled is implemented and indicates that this fence + * can be treated as signaled; false otherwise. */ static inline bool dma_fence_is_signaled_locked(struct dma_fence *fence) @@ -434,9 +441,12 @@ dma_fence_is_signaled_locked(struct dma_fence *fence) * dma_fence_is_signaled - Return an indication if the fence is signaled yet. * @fence: the fence to check * - * Returns true if the fence was already signaled, false if not. Since this - * function doesn't enable signaling, it is not guaranteed to ever return - * true if dma_fence_add_callback(), dma_fence_wait() or + * Checks whether the fence was already signaled, and, if not, whether + * &struct dma_fence_ops.signaled indicates that it should be signaled. If so, + * the fence gets signaled here. + * + * Since this function doesn't enable signaling, it is not guaranteed to ever + * return true if dma_fence_add_callback(), dma_fence_wait() or * dma_fence_enable_sw_signaling() haven't been called before. * * It's recommended for seqno fences to call dma_fence_signal when the @@ -445,6 +455,10 @@ dma_fence_is_signaled_locked(struct dma_fence *fence) * value of this function before calling hardware-specific wait instructions. * * See also dma_fence_is_signaled_locked(). + * + * Return: true if the fence was already signaled, or if + * &struct dma_fence_ops.signaled is implemented and indicates that this fence + * can be treated as signaled; false otherwise. */ static inline bool dma_fence_is_signaled(struct dma_fence *fence) -- 2.48.1
