NAME
clockintr_init,
clockintr_cpu_init,
clockintr_dispatch,
clockintr_setstatclockrate,
clockintr_trigger —
clock interrupt scheduler
SYNOPSIS
#include
<sys/clockintr.h>
void
clockintr_init(u_int flags);
void
clockintr_cpu_init(struct intrclock
*ic);
int
clockintr_dispatch(void
*frame);
void
clockintr_setstatclockrate(int
freq);
void
clockintr_trigger(void);
#include
<sys/kernel.h>
extern int hz;
extern int stathz;
extern int profhz;
#include
<sys/sched.h>
extern int schedhz;
DESCRIPTION
The clockintr_init subsystem maintains a
schedule of events, dispatches expired events, and rearms the local
interrupt clock for each CPU in the system.
The
clockintr_init()
function initializes the subsystem as follows:
- hardclock(9) is configured to run hz(9) times per second on each CPU. It is an error if hz is less than one or greater than one billion.
statclock() is configured to run stathz times per second on each CPU. It is an error if stathz is less than one or greater than one billion.- When appropriate,
statclock() will be reconfigured to run profhz times per second on each CPU. profhz must be a non-zero integer multiple of stathz. It is an error if profhz is less than stathz or greater than one billion. - If schedhz is non-zero,
schedclock() is configured to run schedhz times per second on each CPU. It is an error if schedhz is less than zero or greater than one billion.
The event schedule has a resolution of one nanosecond and event periods are computed using integer division. If hz, stathz, profhz, or schedhz do not divide evenly into one billion, the corresponding event will not be dispatched at the specified frequency.
The
clockintr_init()
function accepts the bitwise OR of zero or more of the following
flags:
CL_RNDSTAT- Randomize the
statclock(). Instead of using a fixed period, the subsystem will select pseudorandom intervals in a range such that the averagestatclock() period is equal to the inverse of stathz.
The
clockintr_init()
function must be called exactly once and only by the primary CPU. It should
be called after all timecounters are installed with
tc_init(9).
The
clockintr_cpu_init()
function prepares the calling CPU for
clockintr_dispatch(). The first time it is called on
a given CPU, if ic is not
NULL, the caller is configured to use the given
intrclock during
clockintr_dispatch(); otherwise the caller is
responsible for rearming its own interrupt clock after each
clockintr_dispatch(). Subsequent calls ignore
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
clockintr_init(). All CPUs should call
clockintr_cpu_init() during each system resume after
the system time is updated with
inittodr(9), otherwise they will needlessly dispatch every event that
expired while the system was suspended.
The
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 frame argument must point
to the caller's clockframe struct. The
clockintr_dispatch() function should only be called
from a clock interrupt handler at IPL_CLOCK (see
spl(9)). It is
an error to call this function on a given CPU before
clockintr_cpu_init().
The
clockintr_setstatclockrate()
function changes the effective dispatch frequency for
statclock()
to freq. It should be called from the
machine-dependent
setstatclockrate()
function after performing any needed hardware reconfiguration. It is an
error if freq is not equal to
stathz or profhz. It is an error
to call this function before the subsystem is initialized with
clockintr_init().
The
clockintr_trigger()
function causes the clockintr_dispatch() function to
run in the appropriate context as soon as possible if the caller was
configured with an intrclock when
clockintr_cpu_init() was first called. If the caller
was not configured with an intrclock, the function
does nothing. It is an error to call this function on a given CPU before
clockintr_cpu_init().
The ic argument to
clockintr_cpu_init()
points to an intrclock structure:
struct intrclock {
void *ic_cookie;
void (*ic_rearm)(void *cookie, uint64_t nsecs);
void (*ic_trigger)(void *cookie);
};
The intrclock structure provides the
clockintr_init subsystem with a uniform interface
for manipulating an interrupt clock. It has the following members:
- ic_cookie
- May point to any resources needed during ic_rearm or ic_trigger to arm the underlying interrupt clock (see below).
- ic_rearm
- Should cause
clockintr_dispatch() to run on the calling CPU in the appropriate context after at least nsecs nanoseconds have elapsed. The first argument, cookie, is the ic_cookie member of the parent structure. The second argument, nsecs, is a non-zero count of nanoseconds. - ic_trigger
- Should cause
clockintr_dispatch() to run on the calling CPU in the appropriate context as soon as possible. The first argument, cookie, is the ic_cookie member of the parent structure.
CONTEXT
The clockintr_init(),
clockintr_cpu_init(), and
clockintr_trigger() functions may be called during
autoconf.
The clockintr_dispatch() function may be
called from interrupt context at IPL_CLOCK.
The clockintr_setstatclockrate() function
may be called during autoconf, from process context, or from interrupt
context.
RETURN VALUES
The clockintr_dispatch() function returns
non-zero if at least one event was dispatched, otherwise it returns
zero.
CODE REFERENCES
sys/kern/kern_clockintr.c
SEE ALSO
hardclock(9), hz(9), inittodr(9), nanouptime(9), spl(9), tc_init(9), timeout(9)
Steven McCanne and Chris Torek, A Randomized Sampling Clock for CPU Utilization Estimation and Code Profiling, In Proc. Winter 1993 USENIX Conference, USENIX Association, pp. 387–394, 1993.
Richard McDougall and Jim Mauro, Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture, Prentice Hall, Sun Microsystems Press, pp. 912–925, 2nd Edition, 2007.
HISTORY
The clockintr_init subsystem first
appeared in OpenBSD 7.3.