Add a draft systimer(9) manpage.
authorVenkatesh Srinivas <me@endeavour.zapto.org>
Fri, 20 Aug 2010 00:52:50 +0000 (17:52 -0700)
committerVenkatesh Srinivas <me@endeavour.zapto.org>
Fri, 20 Aug 2010 00:52:50 +0000 (17:52 -0700)
share/man/man9/Makefile
share/man/man9/systimer.9 [new file with mode: 0644]

index 1776834..af89908 100644 (file)
@@ -145,6 +145,7 @@ MAN=        accept_filter.9 \
        sysctl.9 \
        sysctl_add_oid.9 \
        sysctl_ctx_init.9 \
+       systimer.9 \
        taskqueue.9 \
        time.9 \
        token.9 \
@@ -784,6 +785,11 @@ MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_add.9 \
        sysctl_ctx_init.9 sysctl_ctx_entry_del.9 \
        sysctl_ctx_init.9 sysctl_ctx_entry_find.9 \
        sysctl_ctx_init.9 sysctl_ctx_free.9
+MLINKS+=systimer.9 systimers.9 \
+       systimer.9 systimer_init_periodic.9 \
+       systimer.9 systimer_init_periodic_nq.9 \
+       systimer.9 systimer_init_oneshot.9 \
+       systimer.9 systimer_adjust_periodic.9
 MLINKS+=taskqueue.9 TASK_INIT.9 \
        taskqueue.9 taskqueue_block.9 \
        taskqueue.9 taskqueue_create.9 \
diff --git a/share/man/man9/systimer.9 b/share/man/man9/systimer.9
new file mode 100644 (file)
index 0000000..ad37851
--- /dev/null
@@ -0,0 +1,101 @@
+.\"
+.\" Copyright (c) 2010, The DragonFly Project.
+.\"
+.\" This software is derived from software contributed to the DragonFly Project
+.\" by Venkatesh Srinivas <me@endeavour.zapto.org>.
+.\"
+.\" Permission to use, copy, modify, or distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR OTHER DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA, OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd August 19, 2010
+.Os
+.Dt SYSTIMER 9
+.Sh NAME
+.Nm systimer_init_periodic ,
+.Nm systimer_init_periodic_nq ,
+.Nm systimer_adjust_periodic ,
+.Nm systimer_init_oneshot
+.Nd periodic callbacks
+.Sh SYNOPSIS
+.In sys/systimer.h
+.Ft void
+.Fn systimer_init_periodic "systimer_t info" "void *func" "void *data" "int hz"
+.Ft void
+.Fn systimer_init_periodic_nq "systimer_t info" "void *func" "void *data" "int hz"
+.Ft void
+.Fn systimer_adjust_periodic "systimer_t info" "int hz"
+.Ft void
+.Fn systimer_init_oneshot "systimer_t info" "void *func" "void *data" "int us"
+.Sh DESCRIPTION
+.Pp
+Systimers invoke callbacks at either fixed frequencies or after time delays. The
+callbacks are invoked in an interrupt thread and should only be used for limited
+work.
+.Pp
+The 
+.Fn systimer_init_periodic
+function initializes a systimer callback function to be called at frequency
+.Fa hz .
+The
+.Fa info 
+argument is an allocated systimer structure; the 
+.Fa func
+argument is the function to call, with argument
+.Fa data .
+.Pp
+The 
+.Fn systimer_init_periodic_nq
+function initializes a systimer callback function to be called at a frequency
+.Fa hz .
+Unlike the 
+.Fn systimer_init_periodic
+function, the 
+.Fn systimer_init_periodic_nq
+function's callback is only called once at a given time, even if delays caused
+multiple time intervals to have occured.
+.Pp
+The
+.Fn systimer_adjust_periodic
+function changes the frequency at which a systimer's callback is invoked. The
+current time interval is not affected. The 
+.Fa hz
+argument specifies the new frequency.
+.Pp
+The
+.Fn systimer_init_oneshot
+function arranges for a systimer callback function
+.Fa func
+to be invoked with argument
+.Fa data
+once, after at least
+.Fa us
+microseconds. 
+.Sh EXAMPLE
+A simple example of using a one-short systimer to call a function after a short
+time:
+.Bd -literal
+...
+static struct systimer short_st;
+char *str = "goodbye!";
+...
+systimer_init_oneshot(&short_st, panic, str, 1000);
+...
+.Ed
+.Sh FILES
+The systimer implementation is in
+.Pa /sys/kern/kern_systimer.c .
+.Sh SEE ALSO
+.Xr callout 9
+.Sh HISTORY
+Systimers first appeared in
+.Dx 1.0 .
+