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 | */ |
54 | enum 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 | */ |
66 | extern const uint64_t kptimer_minperiods_ns[KTPL_MAX]; |
67 | |
68 | /* |
69 | * Called from the kernel startup thread to set up kptimer. |
70 | */ |
71 | void kptimer_init(void); |
72 | |
73 | /* |
74 | * Return the minimum timer period in Mach time units. |
75 | */ |
76 | uint64_t kptimer_min_period_abs(bool pet); |
77 | |
78 | /* |
79 | * Return the number of timers available. |
80 | */ |
81 | unsigned 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 | */ |
88 | int 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 | */ |
95 | int 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 | */ |
102 | int 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 | */ |
108 | int 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 | */ |
113 | int kptimer_set_action(unsigned int timer, uint32_t actionid); |
114 | |
115 | /* |
116 | * Set the PET timer to the timer identified by `timerid`. |
117 | */ |
118 | int kptimer_set_pet_timerid(unsigned int timerid); |
119 | |
120 | /* |
121 | * Return the ID of the PET timer. |
122 | */ |
123 | unsigned 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 | */ |
129 | void kptimer_pet_enter(uint64_t sampledur_abs); |
130 | |
131 | /* |
132 | * Start all active timers. The ktrace lock must be held. |
133 | */ |
134 | void kptimer_start(void); |
135 | |
136 | /* |
137 | * Stop all active timers, waiting for them to stop. The ktrace lock must be held. |
138 | */ |
139 | void kptimer_stop(void); |
140 | |
141 | /* |
142 | * Cancel outstanding kperf timer for this CPU. |
143 | */ |
144 | void kptimer_stop_curcpu(void); |
145 | |
146 | /* |
147 | * Reconfigure this CPU's kptimer expiration when it's brought online |
148 | */ |
149 | void kptimer_curcpu_up(void); |
150 | |
151 | /* |
152 | * To indicate the next timer has expired. |
153 | */ |
154 | void kptimer_expire(processor_t processor, int cpuid, uint64_t now); |
155 | |
156 | /* |
157 | * Reset the kptimer system. |
158 | */ |
159 | void kptimer_reset(void); |
160 | |
161 | #endif /* !defined(KPERF_KPTIMER_H) */ |
162 | |