*** UNIX MANUAL PAGE BROWSER ***

CLOCKINTR(9) FreeBSD Kernel Developer's Manual CLOCKINTR(9) 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 average statclock() 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. FreeBSD 14.1-RELEASE-p8 November 10, 2022 FreeBSD 14.1-RELEASE-p8