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