From owner-svn-src-stable@FreeBSD.ORG Mon Jan 2 19:51:12 2012 Return-Path: Delivered-To: svn-src-stable@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id D9E1B106564A; Mon, 2 Jan 2012 19:51:12 +0000 (UTC) (envelope-from mav@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id B8B8E8FC0C; Mon, 2 Jan 2012 19:51:12 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q02JpCW7083564; Mon, 2 Jan 2012 19:51:12 GMT (envelope-from mav@svn.freebsd.org) Received: (from mav@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q02JpC1H083560; Mon, 2 Jan 2012 19:51:12 GMT (envelope-from mav@svn.freebsd.org) Message-Id: <201201021951.q02JpC1H083560@svn.freebsd.org> From: Alexander Motin Date: Mon, 2 Jan 2012 19:51:12 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-9@freebsd.org X-SVN-Group: stable-9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r229314 - in stable/9/share/man: man4 man9 X-BeenThere: svn-src-stable@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for all the -stable branches of the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 02 Jan 2012 19:51:13 -0000 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 +.\" 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@FreeBSD.org