diff options
Diffstat (limited to 'static/openbsd/man9/clockintr.9')
| -rw-r--r-- | static/openbsd/man9/clockintr.9 | 333 |
1 files changed, 333 insertions, 0 deletions
diff --git a/static/openbsd/man9/clockintr.9 b/static/openbsd/man9/clockintr.9 new file mode 100644 index 00000000..a2486aa6 --- /dev/null +++ b/static/openbsd/man9/clockintr.9 @@ -0,0 +1,333 @@ +.\" $OpenBSD: clockintr.9,v 1.3 2022/11/10 23:57:31 jsg Exp $ +.\" +.\" Copyright (c) 2020-2022 Scott Cheloha <cheloha@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: November 10 2022 $ +.Dt CLOCKINTR 9 +.Os +.Sh NAME +.Nm clockintr_init , +.Nm clockintr_cpu_init , +.Nm clockintr_dispatch , +.Nm clockintr_setstatclockrate , +.Nm clockintr_trigger +.Nd clock interrupt scheduler +.Sh SYNOPSIS +.In sys/clockintr.h +.Ft void +.Fo clockintr_init +.Fa "u_int flags" +.Fc +.Ft void +.Fo clockintr_cpu_init +.Fa "struct intrclock *ic" +.Fc +.Ft int +.Fo clockintr_dispatch +.Fa "void *frame" +.Fc +.Ft void +.Fo clockintr_setstatclockrate +.Fa "int freq" +.Fc +.Ft void +.Fo clockintr_trigger +.Fa "void" +.Fc +.In sys/kernel.h +.Vt extern int hz; +.Vt extern int stathz; +.Vt extern int profhz; +.In sys/sched.h +.Vt extern int schedhz; +.Sh DESCRIPTION +The +.Nm +subsystem maintains a schedule of events, +dispatches expired events, +and rearms the local interrupt clock for each CPU in the system. +.Pp +The +.Fn clockintr_init +function initializes the subsystem as follows: +.Bl -dash +.It +.Xr hardclock 9 +is configured to run +.Xr hz 9 +times per second on each CPU. +It is an error if +.Vt hz +is less than one or greater than one billion. +.It +.Fn statclock +is configured to run +.Vt stathz +times per second on each CPU. +It is an error if +.Vt stathz +is less than one or greater than one billion. +.It +When appropriate, +.Fn statclock +will be reconfigured to run +.Vt profhz +times per second on each CPU. +.Vt profhz +must be a non-zero integer multiple of +.Vt stathz . +It is an error if +.Vt profhz +is less than +.Vt stathz +or greater than one billion. +.It +If +.Vt schedhz +is non-zero, +.Fn schedclock +is configured to run +.Vt schedhz +times per second on each CPU. +It is an error if +.Vt schedhz +is less than zero or greater than one billion. +.El +.Pp +The event schedule has a resolution of one nanosecond and event periods are +computed using integer division. +If +.Vt hz , +.Vt stathz , +.Vt profhz , +or +.Vt schedhz +do not divide evenly into one billion, +the corresponding event will not be dispatched at the specified frequency. +.Pp +The +.Fn clockintr_init +function accepts the bitwise OR of zero or more of the following +.Fa flags : +.Bl -tag -width CL_RNDSTAT +.It Dv CL_RNDSTAT +Randomize the +.Fn statclock . +Instead of using a fixed period, +the subsystem will select pseudorandom intervals in a range such that +the average +.Fn statclock +period is equal to the inverse of +.Vt stathz . +.El +.Pp +The +.Fn clockintr_init +function must be called exactly once and only by the primary CPU. +It should be called after all timecounters are installed with +.Xr tc_init 9 . +.Pp +The +.Fn clockintr_cpu_init +function prepares the calling CPU for +.Fn clockintr_dispatch . +The first time it is called on a given CPU, +if +.Fa ic +is not +.Dv NULL , +the caller is configured to use the given +.Fa intrclock +during +.Fn clockintr_dispatch ; +otherwise the caller is responsible for rearming its own interrupt +clock after each +.Fn clockintr_dispatch . +Subsequent calls ignore +.Fa ic : +instead, +the caller's event schedule is advanced past any expired events +without dispatching those events. +It is an error to call this function before the subsystem is initialized with +.Fn clockintr_init . +All CPUs should call +.Fn clockintr_cpu_init +during each system resume after the system time is updated with +.Xr inittodr 9 , +otherwise they will needlessly dispatch every event that expired while +the system was suspended. +.Pp +The +.Fn clockintr_dispatch +function executes all expired events on the caller's event schedule and, +if configured, +rearms the caller's interrupt clock to fire when the next event is scheduled +to expire. +The +.Fa frame +argument must point to the caller's +.Dv clockframe +struct. +The +.Fn clockintr_dispatch +function should only be called from a clock interrupt handler at +.Dv IPL_CLOCK +.Pq see Xr spl 9 . +It is an error to call this function on a given CPU before +.Fn clockintr_cpu_init . +.Pp +The +.Fn clockintr_setstatclockrate +function changes the effective dispatch frequency for +.Fn statclock +to +.Fa freq . +It should be called from the machine-dependent +.Fn setstatclockrate +function after performing any needed hardware reconfiguration. +It is an error if +.Fa freq +is not equal to +.Vt stathz +or +.Vt profhz . +It is an error to call this function before the subsystem is initialized with +.Fn clockintr_init . +.Pp +The +.Fn clockintr_trigger +function causes the +.Fn clockintr_dispatch +function to run in the appropriate context as soon as possible if +the caller was configured with an +.Fa intrclock +when +.Fn clockintr_cpu_init +was first called. +If the caller was not configured with an +.Fa intrclock , +the function does nothing. +It is an error to call this function on a given CPU before +.Fn clockintr_cpu_init . +.Pp +The +.Fa ic +argument to +.Fn clockintr_cpu_init +points to an +.Fa intrclock +structure: +.Bd -literal -offset indent +struct intrclock { + void *ic_cookie; + void (*ic_rearm)(void *cookie, uint64_t nsecs); + void (*ic_trigger)(void *cookie); +}; +.Ed +.Pp +The +.Fa intrclock +structure provides the +.Nm +subsystem with a uniform interface for manipulating an interrupt clock. +It has the following members: +.Bl -tag -width XXXXXXXXXX +.It Fa ic_cookie +May point to any resources needed during +.Fa ic_rearm +or +.Fa ic_trigger +to arm the underlying interrupt clock +.Pq see below . +.It Fa ic_rearm +Should cause +.Fn clockintr_dispatch +to run on the calling CPU in the appropriate context after at least +.Fa nsecs +nanoseconds have elapsed. +The first argument, +.Fa cookie , +is the +.Fa ic_cookie +member of the parent structure. +The second argument, +.Fa nsecs , +is a non-zero count of nanoseconds. +.It Fa ic_trigger +Should cause +.Fn clockintr_dispatch +to run on the calling CPU in the appropriate context as soon as possible. +The first argument, +.Fa cookie , +is the +.Fa ic_cookie +member of the parent structure. +.El +.Sh CONTEXT +The +.Fn clockintr_init , +.Fn clockintr_cpu_init , +and +.Fn clockintr_trigger +functions may be called during autoconf. +.Pp +The +.Fn clockintr_dispatch +function may be called from interrupt context at +.Dv IPL_CLOCK . +.Pp +The +.Fn clockintr_setstatclockrate +function may be called during autoconf, +from process context, +or from interrupt context. +.Sh RETURN VALUES +The +.Fn clockintr_dispatch +function returns non-zero if at least one event was dispatched, +otherwise it returns zero. +.Sh CODE REFERENCES +.Pa sys/kern/kern_clockintr.c +.Sh SEE ALSO +.Xr hardclock 9 , +.Xr hz 9 , +.Xr inittodr 9 , +.Xr nanouptime 9 , +.Xr spl 9 , +.Xr tc_init 9 , +.Xr timeout 9 +.Rs +.%A Steven McCanne +.%A Chris Torek +.%T A Randomized Sampling Clock for CPU Utilization Estimation and Code Profiling +.%B \&In Proc. Winter 1993 USENIX Conference +.%D 1993 +.%P pp. 387\(en394 +.%I USENIX Association +.Re +.Rs +.%A Richard McDougall +.%A Jim Mauro +.%B Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture +.%I Prentice Hall +.%I Sun Microsystems Press +.%D 2nd Edition, 2007 +.%P pp. 912\(en925 +.Re +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Ox 7.3 . |