CLOCKINTR(9) | 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.

November 10, 2022 | Debian