osfmk/kperf/kptimer.h

   1 /*
   2  * Copyright (c) 2011-2018 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  * To indicate the next timer has expired.
 143  */
 144 void kptimer_expire(processor_t processor, int cpuid, uint64_t now);
 145
 146 /*
 147  * Reset the kptimer system.
 148  */
 149 void kptimer_reset(void);
 150
 151 #endif /* !defined(KPERF_KPTIMER_H) */