[apple/xnu.git] / osfmk / kperf / kptimer.h

/*
 * Copyright (c) 2011-2018 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef KPERF_KPTIMER_H
#define KPERF_KPTIMER_H

/*
 * kptimer is responsible for managing the kperf's on-CPU timers.  These
 * timers sample threads that are running on CPUs at a cadence determined by a
 * specified period.  When they fire, a handler runs the specified action and
 * reprograms the timer to fire again.  To get everything started or stopped,
 * kptimer issues a broadcast IPI to modify kperf's multiplexed per-CPU timer,
 * stored in the machine-dependent per-CPU structure.
 *
 * On-CPU timers are disabled when the CPU they've been programmed for goes idle
 * to prevent waking up the idle CPU when it's not running anything interesting.
 * This logic lives in the platform code that's responsible for entering and
 * exiting idle.
 *
 * Traditional PET is configured here (since it's defined by identifying a timer
 * to use for PET) but its mechanism is in osfmk/kperf/pet.c.  Lightweight PET
 * does use kptimer to increment its generation count, however.
 */

/*
 * The minimum allowed timer period depends on the type of client (foreground vs.
 * background) and timer (on-CPU vs. PET).
 */
enum kptimer_period_limit {
	KTPL_FG,
	KTPL_BG,
	KTPL_FG_PET,
	KTPL_BG_PET,
	KTPL_MAX,
};

/*
 * The minimum timer periods allowed by kperf.  There's no other mechanism
 * to prevent interrupt storms due to kptimer.
 */
extern const uint64_t kptimer_minperiods_ns[KTPL_MAX];

/*
 * Called from the kernel startup thread to set up kptimer.
 */
void kptimer_init(void);

/*
 * Return the minimum timer period in Mach time units.
 */
uint64_t kptimer_min_period_abs(bool pet);

/*
 * Return the number of timers available.
 */
unsigned int kptimer_get_count(void);

/*
 * Set the number of timers available to `count`.
 *
 * Returns 0 on success, and non-0 on error.
 */
int kptimer_set_count(unsigned int count);

/*
 * Return the period of the timer identified by `timerid` in `period_out`.
 *
 * Returns 0 on success, and non-0 on error.
 */
int kptimer_get_period(unsigned int timerid, uint64_t *period_out);

/*
 * Set the period of the timer identified by `timerid` to `period`.
 *
 * Returns non-zero on error, and zero otherwise.
 */
int kptimer_set_period(unsigned int timerid, uint64_t period);

/*
 * Return the action of the timer identified by `timerid` in
 * `actionid_out`.
 */
int kptimer_get_action(unsigned int timerid, uint32_t *actionid_out);

/*
 * Set the action of the timer identified by `timerid` to `actionid`.
 */
int kptimer_set_action(unsigned int timer, uint32_t actionid);

/*
 * Set the PET timer to the timer identified by `timerid`.
 */
int kptimer_set_pet_timerid(unsigned int timerid);

/*
 * Return the ID of the PET timer.
 */
unsigned int kptimer_get_pet_timerid(void);

/*
 * For PET to rearm its timer after its sampling thread took `sampledur_abs`
 * to sample.
 */
void kptimer_pet_enter(uint64_t sampledur_abs);

/*
 * Start all active timers.  The ktrace lock must be held.
 */
void kptimer_start(void);

/*
 * Stop all active timers, waiting for them to stop.  The ktrace lock must be held.
 */
void kptimer_stop(void);

/*
 * To indicate the next timer has expired.
 */
void kptimer_expire(processor_t processor, int cpuid, uint64_t now);

/*
 * Reset the kptimer system.
 */
void kptimer_reset(void);

#endif /* !defined(KPERF_KPTIMER_H) */
Commit	Line	Data
f427ee49 A	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) */