Hi Thomas,
On 20/08/26 03:54, Thomas Zimmermann wrote:
[...]
+
+/**
+ * drm_timeout_rel_to_jiffies - calculate jiffies timeout from
relative value
+ *
+ * @timeout_nsec: relative timeout in ns, 0 for poll
+ *
+ * Calculate the timeout in jiffies from a relative timeout in ns,
for drivers
+ * whose UAPI expresses a wait as a duration rather than as a deadline.
+ *
+ * The result is clamped to MAX_JIFFY_OFFSET. That keeps it positive
once it is
+ * converted to the signed long taken by dma_fence_wait_timeout() and
friends,
+ * which matters on 32-bit, and keeps it distinct from
MAX_SCHEDULE_TIMEOUT so
+ * that a finite wait is never understood as an infinite one.
+ *
+ * It's strongly discouraged to use relative timeouts in uAPIs, as
they do not
+ * survive a restarted ioctl. A signal-interrupted ioctl is re-
entered with the
+ * same arguments, so the duration starts counting from zero again.
New uAPIs
+ * should take an absolute deadline and use
drm_timeout_abs_to_jiffies().
I would not speak of uAPIs here, as it's unrelated to the function at
hand. You might want to mention it in the commit description though.
I believe that it's valuable to mention the guidelines to use a function
in the kerneldoc, considering that developers often read the
documentation before using the functions. I have the impression that
this information could end up being dismissed if I include it in the
commit message.
As a note, the addition of this information in the documentation was a
request from Christian in v1.
Please also see my comments on the docs of drm_timeout_abs_to_jiffies().
Most of it applies here as well.
Ack.
Best regards,
- Maíra
