1.\" 2.\" Copyright (c) 2011-2013 Alexander Motin <mav@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 25, 2013 28.Dt EVENTTIMERS 9 29.Os 30.Sh NAME 31.Nm eventtimers 32.Nd kernel event timers subsystem 33.Sh SYNOPSIS 34.In sys/timeet.h 35.Bd -literal 36struct eventtimer; 37 38typedef int et_start_t(struct eventtimer *et, 39 sbintime_t first, sbintime_t period); 40typedef int et_stop_t(struct eventtimer *et); 41typedef void et_event_cb_t(struct eventtimer *et, void *arg); 42typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); 43 44struct eventtimer { 45 SLIST_ENTRY(eventtimer) et_all; 46 char *et_name; 47 int et_flags; 48#define ET_FLAGS_PERIODIC 1 49#define ET_FLAGS_ONESHOT 2 50#define ET_FLAGS_PERCPU 4 51#define ET_FLAGS_C3STOP 8 52#define ET_FLAGS_POW2DIV 16 53 int et_quality; 54 int et_active; 55 uint64_t et_frequency; 56 sbintime_t et_min_period; 57 sbintime_t et_max_period; 58 et_start_t *et_start; 59 et_stop_t *et_stop; 60 et_event_cb_t *et_event_cb; 61 et_deregister_cb_t *et_deregister_cb; 62 void *et_arg; 63 void *et_priv; 64 struct sysctl_oid *et_sysctl; 65}; 66.Ed 67.Ft int 68.Fn et_register "struct eventtimer *et" 69.Ft int 70.Fn et_deregister "struct eventtimer *et" 71.Fn ET_LOCK 72.Fn ET_UNLOCK 73.Ft struct eventtimer * 74.Fn et_find "const char *name" "int check" "int want" 75.Ft int 76.Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg" 77.Ft int 78.Fn et_start "struct eventtimer *et" "sbintime_t first" "sbintime_t period" 79.Ft int 80.Fn et_stop "struct eventtimer *et" 81.Ft int 82.Fn et_ban "struct eventtimer *et" 83.Ft int 84.Fn et_free "struct eventtimer *et" 85.Sh DESCRIPTION 86Event timers are responsible for generating interrupts at specified time 87or periodically, to run different time-based events. 88Subsystem consists of three main parts: 89.Bl -tag -width "Consumers" 90.It Drivers 91Manage hardware to generate requested time events. 92.It Consumers 93.Pa sys/kern/kern_clocksource.c 94uses event timers to supply kernel with 95.Fn hardclock , 96.Fn statclock 97and 98.Fn profclock 99time events. 100.It Glue code 101.Pa sys/sys/timeet.h , 102.Pa sys/kern/kern_et.c 103provide APIs for event timer drivers and consumers. 104.El 105.Sh DRIVER API 106Driver API is built around eventtimer structure. 107To register its functionality driver allocates that structure and calls 108.Fn et_register . 109Driver should fill following fields there: 110.Bl -tag -width Va 111.It Va et_name 112Unique name of the event timer for management purposes. 113.It Va et_flags 114Set of flags, describing timer capabilities: 115.Bl -tag -width "ET_FLAGS_PERIODIC" -compact 116.It ET_FLAGS_PERIODIC 117Periodic mode supported. 118.It ET_FLAGS_ONESHOT 119One-shot mode supported. 120.It ET_FLAGS_PERCPU 121Timer is per-CPU. 122.It ET_FLAGS_C3STOP 123Timer may stop in CPU sleep state. 124.It ET_FLAGS_POW2DIV 125Timer supports only 2^n divisors. 126.El 127.It Va et_quality 128Abstract value to certify whether this timecounter is better than the others. 129Higher value means better. 130.It Va et_frequency 131Timer oscillator's base frequency, if applicable and known. 132Used by consumers to predict set of possible frequencies that could be 133obtained by dividing it. 134Should be zero if not applicable or unknown. 135.It Va et_min_period , et_max_period 136Minimal and maximal reliably programmable time periods. 137.It Va et_start 138Driver's timer start function pointer. 139.It Va et_stop 140Driver's timer stop function pointer. 141.It Va et_priv 142Driver's private data storage. 143.El 144.Pp 145After the event timer functionality is registered, it is controlled via 146.Va et_start 147and 148.Va et_stop 149methods. 150.Va et_start 151method is called to start the specified event timer. 152The last two arguments are used to specify time when events should be 153generated. 154.Va first 155argument specifies time period before the first event generated. 156In periodic mode NULL value specifies that first period is equal to the 157.Va period 158argument value. 159.Va period 160argument specifies the time period between following events for the 161periodic mode. 162The NULL value there specifies the one-shot mode. 163At least one of these two arguments should be not NULL. 164When event time arrive, driver should call 165.Va et_event_cb 166callback function, passing 167.Va et_arg 168as the second argument. 169.Va et_stop 170method is called to stop the specified event timer. 171For the per-CPU event timers 172.Va et_start 173and 174.Va et_stop 175methods control timers associated with the current CPU. 176.Pp 177Driver may deregister its functionality by calling 178.Fn et_deregister . 179.Sh CONSUMER API 180.Fn et_find 181allows consumer to find available event timer, optionally matching specific 182name and/or capability flags. 183Consumer may read returned eventtimer structure, but should not modify it. 184When wanted event timer is found, 185.Fn et_init 186should be called for it, submitting 187.Va event 188and optionally 189.Va deregister 190callbacks functions, and the opaque argument 191.Va arg . 192That argument will be passed as argument to the callbacks. 193Event callback function will be called on scheduled time events. 194It is called from the hardware interrupt context, so no sleep is permitted 195there. 196Deregister callback function may be called to report consumer that the event 197timer functionality is no longer available. 198On this call, consumer should stop using event timer before the return. 199.Pp 200After the timer is found and initialized, it can be controlled via 201.Fn et_start 202and 203.Fn et_stop . 204The arguments are the same as described in driver API. 205Per-CPU event timers can be controlled only from specific CPUs. 206.Pp 207.Fn et_ban 208allows consumer to mark event timer as broken via clearing both one-shot and 209periodic capability flags, if it was somehow detected. 210.Fn et_free 211is the opposite to 212.Fn et_init . 213It releases the event timer for other consumers use. 214.Pp 215.Fn ET_LOCK 216and 217.Fn ET_UNLOCK 218macros should be used to manage 219.Xr mutex 9 220lock around 221.Fn et_find , 222.Fn et_init 223and 224.Fn et_free 225calls to serialize access to the list of the registered event timers and the 226pointers returned by 227.Fn et_find . 228.Fn et_start 229and 230.Fn et_stop 231calls should be serialized in consumer's internal way to avoid concurrent 232timer hardware access. 233.Sh SEE ALSO 234.Xr eventtimers 4 235.Sh AUTHORS 236.An Alexander Motin Aq mav@FreeBSD.org 237