OpenBSD manual page server

Manual Page Search Parameters

CLOCKINTR(9) Kernel Developer's Manual CLOCKINTR(9)

clockintr_init, clockintr_cpu_init, clockintr_dispatch, clockintr_setstatclockrate, clockintr_triggerclock interrupt scheduler

#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;

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 () function initializes the subsystem as follows:

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 () function accepts the bitwise OR of zero or more of the following flags:

Randomize the (). Instead of using a fixed period, the subsystem will select pseudorandom intervals in a range such that the average statclock() period is equal to the inverse of stathz.

The () 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 () 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 () 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 () function changes the effective dispatch frequency for () to freq. It should be called from the machine-dependent () 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 () 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 () 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 () 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.

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.

The clockintr_dispatch() function returns non-zero if at least one event was dispatched, otherwise it returns zero.

sys/kern/kern_clockintr.c

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.

The clockintr_init subsystem first appeared in OpenBSD 7.3.

November 10, 2022 OpenBSD-current