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