iokit/IOKit/pwr_mgt/IOPMPrivate.h

   1 /*
   2  * Copyright (c) 2002 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 #ifndef _IOKIT_IOPMPRIVATE_H
  29 #define _IOKIT_IOPMPRIVATE_H
  30
  31 #include <IOKit/pwr_mgt/IOPM.h>
  32
  33 /*****************************************************************************/
  34
  35 // Private power commands issued to root domain
  36 // bits 0-7 in IOPM.h
  37
  38 enum {
  39     kIOPMSetValue                   = (1<<16),
  40     // don't sleep on clamshell closure on a portable with AC connected
  41     kIOPMSetDesktopMode             = (1<<17),
  42     // set state of AC adaptor connected
  43     kIOPMSetACAdaptorConnected      = (1<<18)
  44 };
  45
  46 /*****************************************************************************/
  47 /*****************************************************************************/
  48
  49 /*
  50  * PM notification types
  51  */
  52
  53 /* @constant kIOPMStateConsoleUserShutdown
  54  * @abstract Notification of GUI shutdown state available to kexts.
  55  * @discussion This type can be passed as arguments to registerPMSettingController()
  56  * to receive callbacks.
  57  */
  58 #define kIOPMStateConsoleShutdown   "ConsoleShutdown"
  59
  60 /* @enum ShutdownValues
  61  * @abstract Potential values shared with key kIOPMStateConsoleUserShutdown
  62  */
  63 enum {
  64 /* @constant kIOPMStateConsoleShutdownNone
  65  * @abstract System shutdown (or restart) hasn't started; system is ON.
  66  * @discussion Next state: 2
  67  */
  68     kIOPMStateConsoleShutdownNone   = 1,
  69 /* @constant kIOPMStateConsoleShutdownPossible
  70  * @abstract User has been presented with the option to shutdown or restart. Shutdown may be cancelled.
  71  * @discussion Next state may be: 1, 4
  72  */
  73     kIOPMStateConsoleShutdownPossible = 2,
  74 /* @constant kIOPMStateConsoleShutdownUnderway
  75  * @abstract Shutdown or restart is proceeding. It may still be cancelled.
  76  * @discussion Next state may be: 1, 4. This state is currently unused.
  77  */
  78     kIOPMStateConsoleShutdownUnderway = 3,
  79 /* @constant kIOPMStateConsoleShutdownCertain
  80  * @abstract Shutdown is in progress and irrevocable.
  81  * @discussion State remains 4 until power is removed from CPU.
  82  */
  83     kIOPMStateConsoleShutdownCertain = 4
  84 };
  85
  86 /*****************************************************************************/
  87 /*****************************************************************************/
  88
  89 /* PM Statistics - event indices
  90  * These are arguments to IOPMrootDomain::pmStatsRecordEvent().
  91  */
  92 enum {
  93     kIOPMStatsHibernateImageWrite         = 1,
  94     kIOPMStatsHibernateImageRead,
  95     kIOPMStatsDriversNotify,
  96     kIOPMStatsApplicationNotify,
  97     kIOPMStatsLateDriverAcknowledge,
  98     kIOPMStatsLateAppAcknowledge,
  99
 100     // To designate if you're specifying the start or stop end of
 101     // each of the above events, do a bitwise OR of the appropriate
 102     // Start/Stop flag and pass the result to IOPMrootDomain to record
 103     // the event.
 104     kIOPMStatsEventStartFlag              = (1 << 24),
 105     kIOPMStatsEventStopFlag               = (1 << 25)
 106 };
 107
 108 // Keys for IOPMrootDomain registry properties
 109 #define kIOPMSleepStatisticsKey                 "SleepStatistics"
 110 #define kIOPMSleepStatisticsAppsKey             "AppStatistics"
 111
 112 // Application response statistics
 113 #define kIOPMStatsNameKey                       "Name"
 114 #define kIOPMStatsPIDKey                        "Pid"
 115 #define kIOPMStatsTimeMSKey                     "TimeMS"
 116 #define kIOPMStatsApplicationResponseTypeKey    "ResponseType"
 117 #define kIOPMStatsMessageTypeKey                "MessageType"
 118
 119 // PM Statistics: potential values for the key kIOPMStatsApplicationResponseTypeKey
 120 // entry in the application results array.
 121 #define kIOPMStatsResponseTimedOut      "ResponseTimedOut"
 122 #define kIOPMStatsResponseCancel        "ResponseCancel"
 123 #define kIOPMStatsResponseSlow          "ResponseSlow"
 124
 125 typedef struct {
 126     struct bounds{
 127         uint64_t start;
 128         uint64_t stop;
 129     };
 130
 131     struct bounds    hibWrite;
 132     struct bounds    hibRead;
 133 //    bounds    driverNotifySleep;
 134 //    bounds    driverNotifyWake;
 135 //    bounds    appNotifySleep;
 136 //    bounds    appNotifyWake;
 137 //    OSDictionary    *tardyApps;
 138 //    OSDictionary    *tardyDrivers;
 139 } PMStatsStruct;
 140
 141 /*****************************************************************************/
 142
 143 /* PM RootDomain tracePoints
 144  *
 145  * In the sleep/wake process, we expect the sleep trace points to proceed
 146  * in increasing order. Once sleep begins with code kIOPMTracePointSleepStarted = 0x11,
 147  * we expect sleep to continue in a monotonically increasing order of tracepoints
 148  * to kIOPMTracePointSystemLoginwindowPhase = 0x30. After trace point SystemLoginWindowPhase,
 149  * the system will return to kIOPMTracePointSystemUp = 0x00.
 150  *
 151  * If the trace point decreases (instead of increasing) before reaching kIOPMTracePointSystemUp,
 152  * that indicates that the sleep process was cancelled. The cancel reason shall be indicated
 153  * in the cancel tracepoint. (TBD)
 154  */
 155
 156 enum {
 157 /* When kTracePointSystemUp is the latest tracePoint,
 158    the system is awake. It is not asleep, sleeping, or waking.
 159
 160    * Phase begins: At boot, at completion of wake from sleep,
 161           immediately following kIOPMTracePointSystemLoginwindowPhase.
 162    * Phase ends: When a sleep attempt is initiated.
 163  */
 164     kIOPMTracePointSystemUp                     = 0,
 165
 166 /* When kIOPMTracePointSleepStarted we have just initiated sleep.
 167
 168     Note: The state prior to kIOPMTracePointSleepStarted may be only one of:
 169         * kIOPMTracePointSystemUp
 170         * kIOPMTracePointSystemLoginwindowPhase or
 171
 172    * Phase begins: At initiation of system sleep (idle or forced).
 173    * Phase ends: As we start to notify applications of system sleep.
 174  */
 175     kIOPMTracePointSleepStarted             = 0x11,
 176
 177 /* When kTracePointSystemSleepAppsPhase is the latest tracePoint,
 178    a system sleep has been irrevocably inititated and PM waits
 179    for responses from notified applications.
 180
 181    * Phase begins: Begin to asynchronously fire kIOMessageSystemWillSleep notifications,
 182    *        and in the case of an idle sleep kIOMessageCanSystemSleep as well.
 183    * Phase ends: When we have received all user & interested kernel acknowledgements.
 184  */
 185     kIOPMTracePointSystemSleepAppsPhase         = 0x12,
 186
 187
 188 /* When kIOPMTracePointSystemHibernatePhase is the latest tracePoint,
 189     PM is writing the hiernate image to disk.
 190  */
 191     kIOPMTracePointSystemHibernatePhase         = 0x13,
 192
 193 /* When kTracePointSystemSleepDriversPhase is the latest tracePoint,
 194     PM is iterating the driver tree powering off devices individually.
 195
 196    * Phase begins: When IOPMrootDomain has received all of its power acknowledgements and begins
 197    *        executing IOService::powerDomainWillChangeTo()
 198    * Phase ends: When IOPMrootDomain::powerChangeDone begins executing CPU shutoff code.
 199  */
 200     kIOPMTracePointSystemSleepDriversPhase      = 0x14,
 201
 202 /* When kTracePointSystemSleepPlatformPhase is the latest tracePoint,
 203     all apps and drivers have notified of sleep. Plotfarm is powering
 204     off CPU; or system is asleep; or low level wakeup is underway.
 205
 206     Note: If a system is asleep and then loses power, and it does not have a hibernate
 207         image to restore from (e.g. hibernatemode = 0), then OS X may interpret this power
 208         loss as a system crash in the kTracePointSystemSleepPlatformPhase, since the
 209         power loss resembles a hang or crash, and the power being removed by the user.
 210
 211    * Phase begins: IOPMrootDomain has already shut off drivers, and is now powering off CPU.
 212    * Phase ends: Immediately after CPU's are powered back on during wakeup.
 213  */
 214     kIOPMTracePointSystemSleepPlatformPhase     = 0x15,
 215
 216 /* When kTracePointSystemWakeDriversPhase is the latest tracePoint,
 217     System CPU is powered, PM is notifying drivers of system wake.
 218
 219    * Phase begins: CPU's have successfully powered up and OS is executing.
 220    * Phase ends: All drivers have handled power events & acknowledged completion.
 221         IOPMrootDomain is about to deliver kIOMessageSystemHasPoweredOn.
 222  */
 223     kIOPMTracePointSystemWakeDriversPhase       = 0x21,
 224
 225 /* When kTracePointSystemWakeAppsPhase is the latest tracePoint,
 226    System CPU is powered, PM has powered on each driver.
 227
 228    * Phase begins: IOPMrootDomain::tellChangeUp before sending asynchronous
 229         kIOMessageSystemHasPoweredOn notifications
 230    * Phase ends: IOPMrootDomain::tellChangeUp after sending asynchronous notifications
 231  */
 232     kIOPMTracePointSystemWakeAppsPhase          = 0x22,
 233
 234 /* kIOPMTracePointSystemLoginwindowPhase
 235     This phase represents a several minute window after the system has powered on.
 236     Higher levels of system diagnostics are in a heightened state of alert in this phase,
 237     in case any user errors occurred that we could not detect in software.
 238
 239     This several minute window
 240
 241    * Phase begins: After IOPMrootDomain sends kIOMessageSystemHasPoweredOn message.
 242    * Phase ends: When loginwindow calls IOPMSleepWakeSetUUID(NULL) the system shall
 243         be considered awake and usable. The next phase shall be kIOPMTracePointSystemUp.
 244  */
 245     kIOPMTracePointSystemLoginwindowPhase       = 0x30
 246 };
 247
 248 /*****************************************************************************/
 249
 250 /*
 251 Ê* kIOPMLoginWindowSecurityDebugKey - identifies PM debug data specific to LoginWindow
 252  *  for use with IOPMrootDomain.
 253 Ê*/
 254 #define kIOPMLoginWindowSecurityDebugKey        "LoginWindowSecurity"
 255
 256 // For PM internal use only - key to locate sleep failure results within SCDynamicStore.
 257 #define kIOPMDynamicStoreSleepFailureKey        "SleepFailure"
 258
 259 /*****************************************************************************/
 260
 261 // For IOPMLibPrivate.h
 262 #define kIOPMSleepWakeFailureKey            "PMFailurePhase"
 263 #define kIOPMSleepWakeFailureCodeKey        "PMStatusCode"
 264 #define kIOPMSleepWakeFailureLoginKey       "LWFailurePhase"
 265 #define kIOPMSleepWakeFailureUUIDKey        "UUID"
 266 #define kIOPMSleepWakeFailureDateKey        "Date"
 267
 268 #endif /* ! _IOKIT_IOPMPRIVATE_H */
 269