1/*
2 * Copyright (c) 2019 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#pragma once
30
31#include <machine/machine_routines.h>
32
33#include <stdint.h>
34#include <IOKit/IOService.h>
35
36/*!
37 * @class IOPMGR
38 * @abstract The base class for power managers, such as ApplePMGR.
39 */
40class IOPMGR : public IOService
41{
42 OSDeclareAbstractStructors(IOPMGR);
43
44public:
45 /*!
46 * @function enableCPUCore
47 * @abstract Enable a single CPU core.
48 * @discussion Release a secondary CPU core from reset, and enable
49 * external IRQ delivery to the core. XNU will not
50 * invoke this method on the boot CPU's cpu_id.
51 * @param cpu_id Logical CPU ID of the core.
52 * @param entry_pa Physical address to use as the reset vector on the
53 * secondary CPU. Not all platforms will honor this
54 * parameter; on Apple Silicon RVBAR_EL1 is programmed
55 * by iBoot.
56 */
57 virtual void enableCPUCore(unsigned int cpu_id, uint64_t entry_pa);
58
59 /*!
60 * @function enableCPUCore
61 * @abstract Deprecated - Enable a single CPU core.
62 */
63 virtual void enableCPUCore(unsigned int cpu_id);
64
65 /*!
66 * @function disableCPUCore
67 * @abstract Disable a single CPU core.
68 * @discussion Prepare a secondary CPU core for power down, and
69 * disable external IRQ delivery to the core. XNU
70 * will not invoke this method on the boot CPU's cpu_id.
71 * Note that the enable and disable operations are not
72 * symmetric, as disableCPUCore doesn't actually cut
73 * power to the core.
74 * @param cpu_id Logical CPU ID of the core.
75 */
76 virtual void disableCPUCore(unsigned int cpu_id) = 0;
77
78 /*!
79 * @function enableCPUCluster
80 * @abstract Enable power to a cluster of CPUs.
81 * @discussion Called to power up a CPU cluster if the cluster-wide
82 * voltage rails are disabled (i.e. PIO to the cluster
83 * isn't even working).
84 * @param cluster_id Cluster ID.
85 */
86 virtual void enableCPUCluster(unsigned int cluster_id) = 0;
87
88 /*!
89 * @function disableCPUCluster
90 * @abstract Disable power to a cluster of CPUs.
91 * @discussion Called to disable the voltage rails on a CPU
92 * cluster. This will only be invoked if all CPUs
93 * in the cluster are already disabled. It is
94 * presumed that after this operation completes,
95 * PIO operations to the cluster will cause a
96 * fatal bus error.
97 * @param cluster_id Cluster ID.
98 */
99 virtual void disableCPUCluster(unsigned int cluster_id) = 0;
100
101 /*!
102 * @function initCPUIdle
103 * @abstract Initialize idle-related parameters.
104 * @param info Pointer to the ml_processor_info_t struct that is
105 * being initialized (and hasn't been registered yet).
106 */
107 virtual void initCPUIdle(ml_processor_info_t *info) = 0;
108
109 /*!
110 * @function enterCPUIdle
111 * @abstract Called from cpu_idle() prior to entering the idle state on
112 * the current CPU.
113 * @param newIdleTimeoutTicks If non-NULL, will be overwritten with a new idle timeout value,
114 * in ticks. If the value is 0, XNU will disable the idle timer.
115 */
116 virtual void enterCPUIdle(UInt64 *newIdleTimeoutTicks) = 0;
117
118 /*!
119 * @function exitCPUIdle
120 * @abstract Called from cpu_idle_exit() after leaving the idle state on
121 * the current CPU.
122 * @param newIdleTimeoutTicks If non-NULL, will be overwritten with a new idle timeout value,
123 * in ticks. If the value is 0, XNU will disable the idle timer.
124 */
125 virtual void exitCPUIdle(UInt64 *newIdleTimeoutTicks) = 0;
126
127 /*!
128 * @function updateCPUIdle
129 * @abstract Called from timer_intr() to ask when to schedule the next idle
130 * timeout on the current CPU.
131 * @param newIdleTimeoutTicks If non-NULL, will be overwritten with a new idle timeout value,
132 * in ticks. If the value is 0, XNU will disable the idle timer.
133 */
134 virtual void updateCPUIdle(UInt64 *newIdleTimeoutTicks) = 0;
135};
136