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 April 2, 2014 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.Ft void 72.Fn et_change_frequency "struct eventtimer *et" "uint64_t newfreq" 73.Fn ET_LOCK 74.Fn ET_UNLOCK 75.Ft struct eventtimer * 76.Fn et_find "const char *name" "int check" "int want" 77.Ft int 78.Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg" 79.Ft int 80.Fn et_start "struct eventtimer *et" "sbintime_t first" "sbintime_t period" 81.Ft int 82.Fn et_stop "struct eventtimer *et" 83.Ft int 84.Fn et_ban "struct eventtimer *et" 85.Ft int 86.Fn et_free "struct eventtimer *et" 87.Sh DESCRIPTION 88Event timers are responsible for generating interrupts at specified time 89or periodically, to run different time-based events. 90Subsystem consists of three main parts: 91.Bl -tag -width "Consumers" 92.It Drivers 93Manage hardware to generate requested time events. 94.It Consumers 95.Pa sys/kern/kern_clocksource.c 96uses event timers to supply kernel with 97.Fn hardclock , 98.Fn statclock 99and 100.Fn profclock 101time events. 102.It Glue code 103.Pa sys/sys/timeet.h , 104.Pa sys/kern/kern_et.c 105provide APIs for event timer drivers and consumers. 106.El 107.Sh DRIVER API 108Driver API is built around eventtimer structure. 109To register its functionality driver allocates that structure and calls 110.Fn et_register . 111Driver should fill following fields there: 112.Bl -tag -width Va 113.It Va et_name 114Unique name of the event timer for management purposes. 115.It Va et_flags 116Set of flags, describing timer capabilities: 117.Bl -tag -width "ET_FLAGS_PERIODIC" -compact 118.It ET_FLAGS_PERIODIC 119Periodic mode supported. 120.It ET_FLAGS_ONESHOT 121One-shot mode supported. 122.It ET_FLAGS_PERCPU 123Timer is per-CPU. 124.It ET_FLAGS_C3STOP 125Timer may stop in CPU sleep state. 126.It ET_FLAGS_POW2DIV 127Timer supports only 2^n divisors. 128.El 129.It Va et_quality 130Abstract value to certify whether this timecounter is better than the others. 131Higher value means better. 132.It Va et_frequency 133Timer oscillator's base frequency, if applicable and known. 134Used by consumers to predict set of possible frequencies that could be 135obtained by dividing it. 136Should be zero if not applicable or unknown. 137.It Va et_min_period , et_max_period 138Minimal and maximal reliably programmable time periods. 139.It Va et_start 140Driver's timer start function pointer. 141.It Va et_stop 142Driver's timer stop function pointer. 143.It Va et_priv 144Driver's private data storage. 145.El 146.Pp 147After the event timer functionality is registered, it is controlled via 148.Va et_start 149and 150.Va et_stop 151methods. 152.Va et_start 153method is called to start the specified event timer. 154The last two arguments are used to specify time when events should be 155generated. 156.Va first 157argument specifies time period before the first event generated. 158In periodic mode NULL value specifies that first period is equal to the 159.Va period 160argument value. 161.Va period 162argument specifies the time period between following events for the 163periodic mode. 164The NULL value there specifies the one-shot mode. 165At least one of these two arguments should be not NULL. 166When event time arrive, driver should call 167.Va et_event_cb 168callback function, passing 169.Va et_arg 170as the second argument. 171.Va et_stop 172method is called to stop the specified event timer. 173For the per-CPU event timers 174.Va et_start 175and 176.Va et_stop 177methods control timers associated with the current CPU. 178.Pp 179Driver may deregister its functionality by calling 180.Fn et_deregister . 181.Pp 182If the frequency of the clock hardware can change while it is 183running (for example, during power-saving modes), the driver must call 184.Fn et_change_frequency 185on each change. 186If the given event timer is the active timer, 187.Fn et_change_frequency 188stops the timer on all CPUs, updates 189.Va et->frequency , 190then restarts the timer on all CPUs so that all 191current events are rescheduled using the new frequency. 192If the given timer is not currently active, 193.Fn et_change_frequency 194simply updates 195.Va et->frequency . 196.Sh CONSUMER API 197.Fn et_find 198allows consumer to find available event timer, optionally matching specific 199name and/or capability flags. 200Consumer may read returned eventtimer structure, but should not modify it. 201When wanted event timer is found, 202.Fn et_init 203should be called for it, submitting 204.Va event 205and optionally 206.Va deregister 207callbacks functions, and the opaque argument 208.Va arg . 209That argument will be passed as argument to the callbacks. 210Event callback function will be called on scheduled time events. 211It is called from the hardware interrupt context, so no sleep is permitted 212there. 213Deregister callback function may be called to report consumer that the event 214timer functionality is no longer available. 215On this call, consumer should stop using event timer before the return. 216.Pp 217After the timer is found and initialized, it can be controlled via 218.Fn et_start 219and 220.Fn et_stop . 221The arguments are the same as described in driver API. 222Per-CPU event timers can be controlled only from specific CPUs. 223.Pp 224.Fn et_ban 225allows consumer to mark event timer as broken via clearing both one-shot and 226periodic capability flags, if it was somehow detected. 227.Fn et_free 228is the opposite to 229.Fn et_init . 230It releases the event timer for other consumers use. 231.Pp 232.Fn ET_LOCK 233and 234.Fn ET_UNLOCK 235macros should be used to manage 236.Xr mutex 9 237lock around 238.Fn et_find , 239.Fn et_init 240and 241.Fn et_free 242calls to serialize access to the list of the registered event timers and the 243pointers returned by 244.Fn et_find . 245.Fn et_start 246and 247.Fn et_stop 248calls should be serialized in consumer's internal way to avoid concurrent 249timer hardware access. 250.Sh SEE ALSO 251.Xr eventtimers 4 252.Sh AUTHORS 253.An Alexander Motin Aq Mt mav@FreeBSD.org 254