1/*
2 * Copyright (c) 2011-2021 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29#ifndef KPERF_KPTIMER_H
30#define KPERF_KPTIMER_H
31
32/*
33 * kptimer is responsible for managing the kperf's on-CPU timers. These
34 * timers sample threads that are running on CPUs at a cadence determined by a
35 * specified period. When they fire, a handler runs the specified action and
36 * reprograms the timer to fire again. To get everything started or stopped,
37 * kptimer issues a broadcast IPI to modify kperf's multiplexed per-CPU timer,
38 * stored in the machine-dependent per-CPU structure.
39 *
40 * On-CPU timers are disabled when the CPU they've been programmed for goes idle
41 * to prevent waking up the idle CPU when it's not running anything interesting.
42 * This logic lives in the platform code that's responsible for entering and
43 * exiting idle.
44 *
45 * Traditional PET is configured here (since it's defined by identifying a timer
46 * to use for PET) but its mechanism is in osfmk/kperf/pet.c. Lightweight PET
47 * does use kptimer to increment its generation count, however.
48 */
49
50/*
51 * The minimum allowed timer period depends on the type of client (foreground vs.
52 * background) and timer (on-CPU vs. PET).
53 */
54enum kptimer_period_limit {
55 KTPL_FG,
56 KTPL_BG,
57 KTPL_FG_PET,
58 KTPL_BG_PET,
59 KTPL_MAX,
60};
61
62/*
63 * The minimum timer periods allowed by kperf. There's no other mechanism
64 * to prevent interrupt storms due to kptimer.
65 */
66extern const uint64_t kptimer_minperiods_ns[KTPL_MAX];
67
68/*
69 * Called from the kernel startup thread to set up kptimer.
70 */
71void kptimer_init(void);
72
73/*
74 * Return the minimum timer period in Mach time units.
75 */
76uint64_t kptimer_min_period_abs(bool pet);
77
78/*
79 * Return the number of timers available.
80 */
81unsigned int kptimer_get_count(void);
82
83/*
84 * Set the number of timers available to `count`.
85 *
86 * Returns 0 on success, and non-0 on error.
87 */
88int kptimer_set_count(unsigned int count);
89
90/*
91 * Return the period of the timer identified by `timerid` in `period_out`.
92 *
93 * Returns 0 on success, and non-0 on error.
94 */
95int kptimer_get_period(unsigned int timerid, uint64_t *period_out);
96
97/*
98 * Set the period of the timer identified by `timerid` to `period`.
99 *
100 * Returns non-zero on error, and zero otherwise.
101 */
102int kptimer_set_period(unsigned int timerid, uint64_t period);
103
104/*
105 * Return the action of the timer identified by `timerid` in
106 * `actionid_out`.
107 */
108int kptimer_get_action(unsigned int timerid, uint32_t *actionid_out);
109
110/*
111 * Set the action of the timer identified by `timerid` to `actionid`.
112 */
113int kptimer_set_action(unsigned int timer, uint32_t actionid);
114
115/*
116 * Set the PET timer to the timer identified by `timerid`.
117 */
118int kptimer_set_pet_timerid(unsigned int timerid);
119
120/*
121 * Return the ID of the PET timer.
122 */
123unsigned int kptimer_get_pet_timerid(void);
124
125/*
126 * For PET to rearm its timer after its sampling thread took `sampledur_abs`
127 * to sample.
128 */
129void kptimer_pet_enter(uint64_t sampledur_abs);
130
131/*
132 * Start all active timers. The ktrace lock must be held.
133 */
134void kptimer_start(void);
135
136/*
137 * Stop all active timers, waiting for them to stop. The ktrace lock must be held.
138 */
139void kptimer_stop(void);
140
141/*
142 * Cancel outstanding kperf timer for this CPU.
143 */
144void kptimer_stop_curcpu(void);
145
146/*
147 * Reconfigure this CPU's kptimer expiration when it's brought online
148 */
149void kptimer_curcpu_up(void);
150
151/*
152 * To indicate the next timer has expired.
153 */
154void kptimer_expire(processor_t processor, int cpuid, uint64_t now);
155
156/*
157 * Reset the kptimer system.
158 */
159void kptimer_reset(void);
160
161#endif /* !defined(KPERF_KPTIMER_H) */
162