[PATCH 01/12] drm/xe: Add kerneldoc to xe_wait_user_fence_ioctl()

[Stuart Summers <stuart.summers@intel.com>]

Document the function use case and expectations. Planning
upcoming changes in this file that add some behavioral changes
to the wait queue implementation here, so having the documentation
up front is helpful when describing those upcoming changes.

Signed-off-by: Stuart Summers <stuart.summers@intel.com>
Assisted-by: Copilot:claude-sonnet-4.6
---
 drivers/gpu/drm/xe/xe_wait_user_fence.c | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/drivers/gpu/drm/xe/xe_wait_user_fence.c b/drivers/gpu/drm/xe/xe_wait_user_fence.c
index 51eb940ceb4e..12ceb3efa8ea 100644
--- a/drivers/gpu/drm/xe/xe_wait_user_fence.c
+++ b/drivers/gpu/drm/xe/xe_wait_user_fence.c
@@ -97,6 +97,28 @@ static long to_jiffies_timeout(struct xe_device *xe,
 	return timeout ?: 1;
 }
 
+/**
+ * xe_wait_user_fence_ioctl() - Wait on a user fence
+ * @dev: DRM device
+ * @data: pointer to a &drm_xe_wait_user_fence
+ * @file: DRM file
+ *
+ * Waits until the value at a user-provided memory address satisfies a
+ * comparison condition, or until a timeout expires. The comparison is
+ * performed as (@addr & @mask) OP @value, where OP is one of the
+ * %DRM_XE_UFENCE_WAIT_OP_* operators.
+ *
+ * If an exec queue ID is provided, the wait is aborted early if the
+ * queue enters a reset state. The device-level wait queue is used for
+ * wakeups.
+ *
+ * On return, @timeout is updated to reflect the remaining time (or zero
+ * on expiry), unless %DRM_XE_UFENCE_WAIT_FLAG_ABSTIME is set.
+ *
+ * Return: 0 on success, -ETIME if the timeout expired before the
+ * condition was met, -ERESTARTSYS if interrupted by a signal, -EIO if
+ * the exec queue was reset, or a negative error code on invalid input.
+ */
 int xe_wait_user_fence_ioctl(struct drm_device *dev, void *data,
 			     struct drm_file *file)
 {
-- 
2.43.0