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.Dd April 2, 2014 26.Dt EVENTTIMERS 9 27.Os 28.Sh NAME 29.Nm eventtimers 30.Nd kernel event timers subsystem 31.Sh SYNOPSIS 32.In sys/timeet.h 33.Bd -literal 34struct eventtimer; 35 36typedef int et_start_t(struct eventtimer *et, 37 sbintime_t first, sbintime_t period); 38typedef int et_stop_t(struct eventtimer *et); 39typedef void et_event_cb_t(struct eventtimer *et, void *arg); 40typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); 41 42struct eventtimer { 43 SLIST_ENTRY(eventtimer) et_all; 44 char *et_name; 45 int et_flags; 46#define ET_FLAGS_PERIODIC 1 47#define ET_FLAGS_ONESHOT 2 48#define ET_FLAGS_PERCPU 4 49#define ET_FLAGS_C3STOP 8 50#define ET_FLAGS_POW2DIV 16 51 int et_quality; 52 int et_active; 53 uint64_t et_frequency; 54 sbintime_t et_min_period; 55 sbintime_t et_max_period; 56 et_start_t *et_start; 57 et_stop_t *et_stop; 58 et_event_cb_t *et_event_cb; 59 et_deregister_cb_t *et_deregister_cb; 60 void *et_arg; 61 void *et_priv; 62 struct sysctl_oid *et_sysctl; 63}; 64.Ed 65.Ft int 66.Fn et_register "struct eventtimer *et" 67.Ft int 68.Fn et_deregister "struct eventtimer *et" 69.Ft void 70.Fn et_change_frequency "struct eventtimer *et" "uint64_t newfreq" 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.Pp 180If the frequency of the clock hardware can change while it is 181running (for example, during power-saving modes), the driver must call 182.Fn et_change_frequency 183on each change. 184If the given event timer is the active timer, 185.Fn et_change_frequency 186stops the timer on all CPUs, updates 187.Va et->frequency , 188then restarts the timer on all CPUs so that all 189current events are rescheduled using the new frequency. 190If the given timer is not currently active, 191.Fn et_change_frequency 192simply updates 193.Va et->frequency . 194.Sh CONSUMER API 195.Fn et_find 196allows consumer to find available event timer, optionally matching specific 197name and/or capability flags. 198Consumer may read returned eventtimer structure, but should not modify it. 199When wanted event timer is found, 200.Fn et_init 201should be called for it, submitting 202.Va event 203and optionally 204.Va deregister 205callbacks functions, and the opaque argument 206.Va arg . 207That argument will be passed as argument to the callbacks. 208Event callback function will be called on scheduled time events. 209It is called from the hardware interrupt context, so no sleep is permitted 210there. 211Deregister callback function may be called to report consumer that the event 212timer functionality is no longer available. 213On this call, consumer should stop using event timer before the return. 214.Pp 215After the timer is found and initialized, it can be controlled via 216.Fn et_start 217and 218.Fn et_stop . 219The arguments are the same as described in driver API. 220Per-CPU event timers can be controlled only from specific CPUs. 221.Pp 222.Fn et_ban 223allows consumer to mark event timer as broken via clearing both one-shot and 224periodic capability flags, if it was somehow detected. 225.Fn et_free 226is the opposite to 227.Fn et_init . 228It releases the event timer for other consumers use. 229.Pp 230.Fn ET_LOCK 231and 232.Fn ET_UNLOCK 233macros should be used to manage 234.Xr mutex 9 235lock around 236.Fn et_find , 237.Fn et_init 238and 239.Fn et_free 240calls to serialize access to the list of the registered event timers and the 241pointers returned by 242.Fn et_find . 243.Fn et_start 244and 245.Fn et_stop 246calls should be serialized in consumer's internal way to avoid concurrent 247timer hardware access. 248.Sh SEE ALSO 249.Xr eventtimers 4 250.Sh AUTHORS 251.An Alexander Motin Aq Mt mav@FreeBSD.org 252