MFcalloutng:

Dcoument the new functions added to condvar(9), sleep(9), sleepqueue(9)
KPIs. Also document recent changes in timeout(9) and eventtimers(4).

6 files changed, 136 insertions, 15 deletions

diff --git a/share/man/man4/eventtimers.4 b/share/man/man4/eventtimers.4
index 4db4420..656c8e0 100644
--- a/share/man/man4/eventtimers.4
+++ b/share/man/man4/eventtimers.4
@@ -143,14 +143,6 @@ By default this options is disabled.
 If chosen timer is per-CPU
 and runs in periodic mode, this option has no effect - all interrupts are
 always generating.
-.It Va kern.eventtimer.activetick
-makes each CPU to receive all kinds of timer interrupts when they are busy.
-Disabling it allows to skip some
-.Fn hardclock
-calls in some cases.
-By default this options is enabled.
-If chosen timer is per-CPU, this option has no effect - all interrupts are
-always generating, as timer reprogramming is too expensive for that case.
 .El
 .Sh SEE ALSO
 .Xr apic 4 ,
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 8e96d64..fa7cc8a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1196,9 +1196,13 @@ MLINKS+=signal.9 cursig.9 \
 	signal.9 SIG_STOPSIGMASK.9 \
 	signal.9 trapsignal.9
 MLINKS+=sleep.9 msleep.9 \
+	sleep.9 msleep_sbt.9 \
 	sleep.9 msleep_spin.9 \
+	sleep.9 msleep_spin_sbt.9 \
 	sleep.9 pause.9 \
+	sleep.9 pause_sbt.9 \
 	sleep.9 tsleep.9 \
+	sleep.9 tsleep_sbt.9 \
 	sleep.9 wakeup.9 \
 	sleep.9 wakeup_one.9
 MLINKS+=sleepqueue.9 init_sleepqueues.9 \
@@ -1213,6 +1217,7 @@ MLINKS+=sleepqueue.9 init_sleepqueues.9 \
 	sleepqueue.9 sleepq_release.9 \
 	sleepqueue.9 sleepq_remove.9 \
 	sleepqueue.9 sleepq_set_timeout.9 \
+	sleepqueue.9 sleepq_set_timeout_sbt.9 \
 	sleepqueue.9 sleepq_signal.9 \
 	sleepqueue.9 sleepq_timedwait.9 \
 	sleepqueue.9 sleepq_timedwait_sig.9 \
@@ -1335,6 +1340,9 @@ MLINKS+=timeout.9 callout.9 \
 	timeout.9 callout_init_rw.9 \
 	timeout.9 callout_pending.9 \
 	timeout.9 callout_reset.9 \
+	timeout.9 callout_reset_sbt.9 \
+	timeout.9 callout_reset_on.9 \
+	timeout.9 callout_reset_sbt_on.9 \
 	timeout.9 callout_schedule.9 \
 	timeout.9 callout_stop.9 \
 	timeout.9 untimeout.9
diff --git a/share/man/man9/condvar.9 b/share/man/man9/condvar.9
index 7b89d46..4a4e874 100644
--- a/share/man/man9/condvar.9
+++ b/share/man/man9/condvar.9
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 5, 2007
+.Dd February 19, 2013
 .Dt CONDVAR 9
 .Os
 .Sh NAME
@@ -37,7 +37,9 @@
 .Nm cv_wait_sig ,
 .Nm cv_wait_unlock ,
 .Nm cv_timedwait ,
+.Nm cv_timedwait_sbt ,
 .Nm cv_timedwait_sig ,
+.Nm cv_timedwait_sig_sbt ,
 .Nm cv_signal ,
 .Nm cv_broadcast ,
 .Nm cv_broadcastpri ,
@@ -60,7 +62,13 @@
 .Ft int
 .Fn cv_timedwait "struct cv *cvp" "lock" "int timo"
 .Ft int
+.Fn cv_timedwait_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \
+"sbintime_t pr" "int flags"
+.Ft int
 .Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo"
+.Ft int
+.Fn cv_timedwait_sig_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \
+"sbintime_t pr" "int flags"
 .Ft void
 .Fn cv_signal "struct cv *cvp"
 .Ft void
@@ -191,6 +199,25 @@ if a signal is caught, or 0 if signaled via
 .Fn cv_signal
 or
 .Fn cv_broadcast .
+.Pp
+.Fn cv_timedwait_sbt
+and
+.Fn cv_timedwait_sig_sbt
+functions take
+.Fa sbt
+argument instead of
+.Fa timo .
+It allows to specify relative or absolute unblock time with higher resolution
+in form of
+.Vt sbintime_t .
+The parameter
+.Fa pr
+allows to specify wanted absolute event precision.
+The parameter
+.Fa flags
+allows to pass additional
+.Fn callout_reset_sbt
+flags.
 .Sh RETURN VALUES
 If successful,
 .Fn cv_wait_sig ,
@@ -230,4 +257,5 @@ Timeout expired.
 .Xr rwlock 9 ,
 .Xr sema 9 ,
 .Xr sleep 9 ,
-.Xr sx 9
+.Xr sx 9 ,
+.Xr timeout 9
diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9
index e65a189..4ac9d45 100644
--- a/share/man/man9/sleep.9
+++ b/share/man/man9/sleep.9
@@ -25,14 +25,18 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 12, 2009
+.Dd February 19, 2013
 .Dt SLEEP 9
 .Os
 .Sh NAME
 .Nm msleep ,
+.Nm msleep_sbt ,
 .Nm msleep_spin ,
+.Nm msleep_spin_sbt ,
 .Nm pause ,
+.Nm pause_sbt ,
 .Nm tsleep ,
+.Nm tsleep_sbt ,
 .Nm wakeup
 .Nd wait for events
 .Sh SYNOPSIS
@@ -42,11 +46,23 @@
 .Ft int
 .Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo"
 .Ft int
+.Fn msleep_sbt "void *chan" "struct mtx *mtx" "int priority" \
+"const char *wmesg" "sbintime_t sbt" "sbintime_t pr" "int flags"
+.Ft int
 .Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo"
+.Ft int
+.Fn msleep_spin_sbt "void *chan" "struct mtx *mtx" "const char *wmesg" \
+"sbintime_t sbt" "sbintime_t pr" "int flags"
 .Ft void
 .Fn pause "const char *wmesg" "int timo"
+.Ft void
+.Fn pause_sbt "const char *wmesg" "sbintime_t sbt" "sbintime_t pr" \
+ "int flags"
 .Ft int
 .Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo"
+.Ft int
+.Fn tsleep_sbt "void *chan" "int priority" "const char *wmesg" \
+"sbintime_t sbt" "sbintime_t pr" "int flags"
 .Ft void
 .Fn wakeup "void *chan"
 .Ft void
@@ -148,6 +164,27 @@ If the timeout expires,
 then the sleep function will return
 .Er EWOULDBLOCK .
 .Pp
+.Fn msleep_sbt ,
+.Fn msleep_spin_sbt ,
+.Fn pause_sbt
+and
+.Fn tsleep_sbt
+functions take
+.Fa sbt
+parameter instead of
+.Fa timo .
+It allows to specify relative or absolite wakeup time with higher resolution
+in form of
+.Vt sbintime_t .
+The parameter
+.Fa pr
+allows to specify wanted absolute event precision.
+The parameter
+.Fa flags
+allows to pass additional
+.Fn callout_reset_sbt
+flags.
+.Pp
 Several of the sleep functions including
 .Fn msleep ,
 .Fn msleep_spin ,
@@ -301,7 +338,8 @@ A non-zero timeout was specified and the timeout expired.
 .Xr mi_switch 9 ,
 .Xr mtx_sleep 9 ,
 .Xr rw_sleep 9 ,
-.Xr sx_sleep 9
+.Xr sx_sleep 9 ,
+.Xr timeout 9
 .Sh HISTORY
 The functions
 .Fn sleep
diff --git a/share/man/man9/sleepqueue.9 b/share/man/man9/sleepqueue.9
index 22971d8..8557b9f 100644
--- a/share/man/man9/sleepqueue.9
+++ b/share/man/man9/sleepqueue.9
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 8, 2010
+.Dd February 19, 2013
 .Dt SLEEPQUEUE 9
 .Os
 .Sh NAME
@@ -41,6 +41,7 @@
 .Nm sleepq_remove ,
 .Nm sleepq_signal ,
 .Nm sleepq_set_timeout ,
+.Nm sleepq_set_timeout_sbt ,
 .Nm sleepq_sleepcnt ,
 .Nm sleepq_timedwait ,
 .Nm sleepq_timedwait_sig ,
@@ -79,6 +80,9 @@
 .Fn sleepq_signal "void *wchan" "int flags" "int pri" "int queue"
 .Ft void
 .Fn sleepq_set_timeout "void *wchan" "int timo"
+.Ft void
+.Fn sleepq_set_timeout_sbt "void *wchan" "sbintime_t sbt" \
+"sbintime_t pr" "int flags"
 .Ft u_int
 .Fn sleepq_sleepcnt "void *wchan" "int queue"
 .Ft int
@@ -231,6 +235,23 @@ The
 .Fa timo
 parameter should specify the timeout value in ticks.
 .Pp
+.Fn sleepq_set_timeout_sbt
+function takes
+.Fa sbt
+argument instead of
+.Fa timo .
+It allows to specify relative or absolute wakeup time with higher resolution
+in form of
+.Vt sbintime_t .
+The parameter
+.Fa pr
+allows to specify wanted absolute event precision.
+The parameter
+.Fa flags
+allows to pass additional
+.Fn callout_reset_sbt
+flags.
+.Pp
 The current thread may be marked interruptible by calling
 .Fn sleepq_catch_signals
 with
@@ -400,4 +421,5 @@ than manipulating sleep queues directly.
 .Xr condvar 9 ,
 .Xr runqueue 9 ,
 .Xr scheduler 9 ,
-.Xr sleep 9
+.Xr sleep 9 ,
+.Xr timeout 9
diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9
index c671467..c63c201 100644
--- a/share/man/man9/timeout.9
+++ b/share/man/man9/timeout.9
@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 1, 2012
+.Dd February 19, 2013
 .Dt TIMEOUT 9
 .Os
 .Sh NAME
@@ -44,6 +44,9 @@
 .Nm callout_reset ,
 .Nm callout_reset_on ,
 .Nm callout_reset_curcpu ,
+.Nm callout_reset_sbt ,
+.Nm callout_reset_sbt_on ,
+.Nm callout_reset_sbt_curcpu ,
 .Nm callout_schedule ,
 .Nm callout_schedule_on ,
 .Nm callout_schedule_curcpu ,
@@ -82,6 +85,9 @@ struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle);
 .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \
 "void *arg" "int cpu"
 .Ft int
+.Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \
+"sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags"
+.Ft int
 .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \
 "void *arg"
 .Ft int
@@ -326,6 +332,33 @@ and
 .Fn callout_schedule
 but take an extra parameter specifying the target CPU for the callout.
 .Pp
+The function
+.Fn callout_reset_sbt_on
+allows to get higher time resolution, taking relative or absolute time
+and precision instead of relative ticks count.
+If specified time is in past, it will be silently converted to present
+to run handler as soon as possible.
+.Pp
+The following
+.Fa flags
+may be specified:
+.Bl -tag -width ".Dv C_DIRECT_EXEC"
+.It Dv C_ALSOLUTE
+Handle the
+.Fa sbt
+argument as absolute time of the event since boot, or relative time otherwise.
+.It Dv C_DIRECT_EXEC
+Run handler directly from hardware interrupt context instead of softclock swi.
+It is faster, but puts more constraints on handlers.
+Handlers may use only spin mutexes for locking, and they must be fast because
+they run with absolute priority.
+.It Fn C_PREL
+Specifies relative event time precision as binary logarithm of time interval
+divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc.
+Smaller value allows to aggregate more events in one timer interrupt to
+reduce processing overhead and power consumption.
+.El
+.Pp
 The functions
 .Fn callout_reset_curcpu
 and