[src/trunk]: src/sys/kern Clarify interpretation of timeout/epsilon in cv_tim...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/07f09285dcf2
branches:  trunk
changeset: 357479:07f09285dcf2
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sun Nov 12 19:46:34 2017 +0000

description:
Clarify interpretation of timeout/epsilon in cv_timedwaitbt.

diffstat:

 sys/kern/kern_condvar.c |  17 +++++++++++++----
 1 files changed, 13 insertions(+), 4 deletions(-)

diffs (50 lines):

diff -r 94ce527fe079 -r 07f09285dcf2 sys/kern/kern_condvar.c
--- a/sys/kern/kern_condvar.c   Sun Nov 12 19:46:06 2017 +0000
+++ b/sys/kern/kern_condvar.c   Sun Nov 12 19:46:34 2017 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: kern_condvar.c,v 1.37 2017/07/03 02:12:47 riastradh Exp $      */
+/*     $NetBSD: kern_condvar.c,v 1.38 2017/11/12 19:46:34 riastradh Exp $      */
 
 /*-
  * Copyright (c) 2006, 2007, 2008 The NetBSD Foundation, Inc.
@@ -34,7 +34,7 @@
  */
 
 #include <sys/cdefs.h>
-__KERNEL_RCSID(0, "$NetBSD: kern_condvar.c,v 1.37 2017/07/03 02:12:47 riastradh Exp $");
+__KERNEL_RCSID(0, "$NetBSD: kern_condvar.c,v 1.38 2017/11/12 19:46:34 riastradh Exp $");
 
 #include <sys/param.h>
 #include <sys/systm.h>
@@ -391,20 +391,29 @@
  *
  *     On entry, bt is a timeout in bintime.  cv_timedwaitbt subtracts
  *     the time slept, so on exit, bt is the time remaining after
- *     sleeping.  No infinite timeout; use cv_wait_sig instead.
+ *     sleeping, possibly negative if the complete time has elapsed.
+ *     No infinite timeout; use cv_wait_sig instead.
  *
  *     epsilon is a requested maximum error in timeout (excluding
  *     spurious wakeups).  Currently not used, will be used in the
  *     future to choose between low- and high-resolution timers.
+ *     Actual wakeup time will be somewhere in [t, t + max(e, r) + s)
+ *     where r is the finest resolution of clock available and s is
+ *     scheduling delays for scheduler overhead and competing threads.
+ *     Time is measured by the interrupt source implementing the
+ *     timeout, not by another timecounter.
  */
 int
 cv_timedwaitbt(kcondvar_t *cv, kmutex_t *mtx, struct bintime *bt,
-    const struct bintime *epsilon __unused)
+    const struct bintime *epsilon __diagused)
 {
        struct bintime slept;
        unsigned start, end;
        int error;
 
+       KASSERTMSG(bt->sec >= 0, "negative timeout");
+       KASSERTMSG(epsilon != NULL, "specify maximum requested delay");
+
        /*
         * hardclock_ticks is technically int, but nothing special
         * happens instead of overflow, so we assume two's-complement