svn commit: r229314 - in stable/9/share/man: man4 man9
Alexander Motin
mav at FreeBSD.org
Mon Jan 2 19:51:13 UTC 2012
Author: mav
Date: Mon Jan 2 19:51:12 2012
New Revision: 229314
URL: http://svn.freebsd.org/changeset/base/229314
Log:
MFC r228731:
Add eventtimers(9) man page, describing related KPIs.
Sponsored by: iXsystems, Inc.
Added:
stable/9/share/man/man9/eventtimers.9
- copied unchanged from r228731, head/share/man/man9/eventtimers.9
Modified:
stable/9/share/man/man4/eventtimers.4
stable/9/share/man/man9/Makefile
Directory Properties:
stable/9/share/man/man4/ (props changed)
stable/9/share/man/man9/ (props changed)
Modified: stable/9/share/man/man4/eventtimers.4
==============================================================================
--- stable/9/share/man/man4/eventtimers.4 Mon Jan 2 19:49:01 2012 (r229313)
+++ stable/9/share/man/man4/eventtimers.4 Mon Jan 2 19:51:12 2012 (r229314)
@@ -147,4 +147,5 @@ always generating.
.Sh SEE ALSO
.Xr atrtc 4 ,
.Xr attimer 4 ,
-.Xr hpet 4
+.Xr hpet 4 ,
+.Xr eventtimers 9
Modified: stable/9/share/man/man9/Makefile
==============================================================================
--- stable/9/share/man/man9/Makefile Mon Jan 2 19:49:01 2012 (r229313)
+++ stable/9/share/man/man9/Makefile Mon Jan 2 19:51:12 2012 (r229314)
@@ -102,6 +102,7 @@ MAN= accept_filter.9 \
driver.9 \
DRIVER_MODULE.9 \
EVENTHANDLER.9 \
+ eventtimers.9 \
extattr.9 \
fail.9 \
fetch.9 \
@@ -613,6 +614,16 @@ MLINKS+=EVENTHANDLER.9 EVENTHANDLER_DECL
EVENTHANDLER.9 eventhandler_prune_list.9 \
EVENTHANDLER.9 EVENTHANDLER_REGISTER.9 \
EVENTHANDLER.9 eventhandler_register.9
+MLINKS+=eventtimers.9 et_register.9 \
+ eventtimers.9 et_deregister.9 \
+ eventtimers.9 et_ban.9 \
+ eventtimers.9 et_find.9 \
+ eventtimers.9 et_free.9 \
+ eventtimers.9 et_init.9 \
+ eventtimers.9 ET_LOCK.9 \
+ eventtimers.9 ET_UNLOCK.9 \
+ eventtimers.9 et_start.9 \
+ eventtimers.9 et_stop.9
MLINKS+=fetch.9 fubyte.9 \
fetch.9 fuswintr.9 \
fetch.9 fuword.9 \
Copied: stable/9/share/man/man9/eventtimers.9 (from r228731, head/share/man/man9/eventtimers.9)
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ stable/9/share/man/man9/eventtimers.9 Mon Jan 2 19:51:12 2012 (r229314, copy of r228731, head/share/man/man9/eventtimers.9)
@@ -0,0 +1,236 @@
+.\"
+.\" Copyright (c) 2011 Alexander Motin <mav at FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 14, 2011
+.Dt EVENTTIMERS 9
+.Os
+.Sh NAME
+.Nm eventtimers
+.Nd kernel event timers subsystem
+.Sh SYNOPSIS
+.In sys/timeet.h
+.Bd -literal
+struct eventtimer;
+
+typedef int et_start_t(struct eventtimer *et,
+ struct bintime *first, struct bintime *period);
+typedef int et_stop_t(struct eventtimer *et);
+typedef void et_event_cb_t(struct eventtimer *et, void *arg);
+typedef int et_deregister_cb_t(struct eventtimer *et, void *arg);
+
+struct eventtimer {
+ SLIST_ENTRY(eventtimer) et_all;
+ char *et_name;
+ int et_flags;
+#define ET_FLAGS_PERIODIC 1
+#define ET_FLAGS_ONESHOT 2
+#define ET_FLAGS_PERCPU 4
+#define ET_FLAGS_C3STOP 8
+#define ET_FLAGS_POW2DIV 16
+ int et_quality;
+ int et_active;
+ u_int64_t et_frequency;
+ struct bintime et_min_period;
+ struct bintime et_max_period;
+ et_start_t *et_start;
+ et_stop_t *et_stop;
+ et_event_cb_t *et_event_cb;
+ et_deregister_cb_t *et_deregister_cb;
+ void *et_arg;
+ void *et_priv;
+ struct sysctl_oid *et_sysctl;
+};
+.Ed
+.Ft int
+.Fn et_register "struct eventtimer *et"
+.Ft int
+.Fn et_deregister "struct eventtimer *et"
+.Fn ET_LOCK
+.Fn ET_UNLOCK
+.Ft struct eventtimer *
+.Fn et_find "const char *name" "int check" "int want"
+.Ft int
+.Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg"
+.Ft int
+.Fn et_start "struct eventtimer *et" "struct bintime *first" "struct bintime *period"
+.Ft int
+.Fn et_stop "struct eventtimer *et"
+.Ft int
+.Fn et_ban "struct eventtimer *et"
+.Ft int
+.Fn et_free "struct eventtimer *et"
+.Sh DESCRIPTION
+Event timers are responsible for generating interrupts at specified time
+or periodically, to run different time-based events.
+Subsystem consists of three main parts:
+.Bl -tag
+.It Drivers
+Manage hardware to generate requested time events.
+.It Consumers
+.Pa sys/kern/kern_clocksource.c
+uses event timers to supply kernel with
+.Fn hardclock ,
+.Fn statclock
+and
+.Fn profclock
+time events.
+.It Glue code
+.Pa sys/sys/timeet.h ,
+.Pa sys/kern/kern_et.c
+provide APIs for event timer drivers and consumers.
+.El
+.Sh DRIVER API
+Driver API is built around eventtimer structure.
+To register its functionality driver allocates that structure and calls
+.Fn et_register .
+Driver should fill following fields there:
+.Bl -tag
+.It Va et_name
+Unique name of the event timer for management purposes.
+.It Va et_flags
+Set of flags, describing timer capabilities:
+.Bl -tag -width "ET_FLAGS_PERIODIC" -compact
+.It ET_FLAGS_PERIODIC
+Periodic mode supported.
+.It ET_FLAGS_ONESHOT
+One-shot mode supported.
+.It ET_FLAGS_PERCPU
+Timer is per-CPU.
+.It ET_FLAGS_C3STOP
+Timer may stop in CPU sleep state.
+.It ET_FLAGS_POW2DIV
+Timer supports only 2^n divisors.
+.El
+.It Va et_quality
+Abstract value to certify whether this timecounter is better than the others.
+Higher value means better.
+.It Va et_frequency
+Timer oscillator's base frequency, if applicable and known.
+Used by consumers to predict set of possible frequencies that could be
+obtained by dividing it.
+Should be zero if not applicable or unknown.
+.It Va et_min_period , et_max_period
+Minimal and maximal reliably programmable time periods.
+.It Va et_start
+Driver's timer start function pointer.
+.It Va et_stop
+Driver's timer stop function pointer.
+.It Va et_priv
+Driver's private data storage.
+.El
+.Pp
+After the event timer functionality is registered, it is controlled via
+.Va et_start
+and
+.Va et_stop
+methods.
+.Va et_start
+method is called to start the specified event timer.
+The last two arguments are used to specify time when events should be
+generated.
+.Va first
+argument specifies time period before the first event generated.
+In periodic mode NULL value specifies that first period is equal to the
+.Va period
+argument value.
+.Va period
+argument specifies the time period between following events for the
+periodic mode.
+The NULL value there specifies the one-shot mode.
+At least one of these two arguments should be not NULL.
+When event time arrive, driver should call
+.Va et_event_cb
+callback function, passing
+.Va et_arg
+as the second argument.
+.Va et_stop
+method is called to stop the specified event timer.
+For the per-CPU event timers
+.Va et_start
+and
+.Va et_stop
+methods control timers associated with the current CPU.
+.Pp
+Driver may deregister its functionality by calling
+.Fn et_deregister .
+.Sh CONSUMER API
+.Fn et_find
+allows consumer to find available event timer, optionally matching specific
+name and/or capability flags.
+Consumer may read returned eventtimer structure, but should not modify it.
+When wanted event timer is found,
+.Fn et_init
+should be called for it, submitting
+.Va event
+and optionally
+.Va deregister
+callbacks functions, and the opaque argument
+.Va arg .
+That argument will be passed as argument to the callbacks.
+Event callback function will be called on scheduled time events.
+It is called from the hardware interrupt context, so no sleep is permitted
+there.
+Deregister callback function may be called to report consumer that the event
+timer functionality is no longer available.
+On this call, consumer should stop using event timer before the return.
+.Pp
+After the timer is found and initialized, it can be controlled via
+.Fn et_start
+and
+.Fn et_stop .
+The arguments are the same as described in driver API.
+Per-CPU event timers can be controlled only from specific CPUs.
+.Pp
+.Fn et_ban
+allows consumer to mark event timer as broken via clearing both one-shot and
+periodic capability flags, if it was somehow detected.
+.Fn et_free
+is the opposite to
+.Fn et_init .
+It releases the event timer for other consumers use.
+.Pp
+.Fn ET_LOCK
+and
+.Fn ET_UNLOCK
+macros should be used to manage
+.Xr mutex 9
+lock around
+.Fn et_find ,
+.Fn et_init
+and
+.Fn et_free
+calls to serialize access to the list of the registered event timers and the
+pointers returned by
+.Fn et_find .
+.Fn et_start
+and
+.Fn et_stop
+calls should be serialized in consumer's internal way to avoid concurrent
+timer hardware access.
+.Sh SEE ALSO
+.Xr eventtimers 4
+.Sh AUTHORS
+.An Alexander Motin Aq mav at FreeBSD.org
More information about the svn-src-stable-9
mailing list