iokit/IOKit/IOPMGR.h

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