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#pragma mark PM Timeline Logging
34/**************************************************
35*
36* Timeline API Keys - Reports timing details for
37*   applications, drivers, and system during PM activity
38*
39* For kernel-internal use only
40**************************************************/
41
42// Keys for interfacing with IOPMrootDomain Timeline
43/* @constant kIOPMTimelineDictionaryKey
44 * @abstract RootDomain key for dictionary describing Timeline's info
45 */
46#define kIOPMTimelineDictionaryKey              "PMTimelineLogging"
47
48/* @constant kIOPMTimelineEnabledKey
49 * @abstract Boolean value indicating whether the system is recording PM events.
50 * @discussion Key may be found in the dictionary at IOPMrootDomain's property
51 * kIOPMTimelineDictionaryKey. uint32_t value; may be 0.
52 */
53#define kIOPMTimelineEnabledKey                 "TimelineEnabled"
54
55/* @constant kIOMPTimelineSystemNumberTrackedKey
56 * @abstract The maximum number of system power events the system may record.
57 * @discussion Key may be found in the dictionary at IOPMrootDomain's property
58 * kIOPMTimelineDictionaryKey. uint32_t value; may be 0.
59 */
60#define kIOPMTimelineSystemNumberTrackedKey     "TimelineSystemEventsTracked"
61
62/* @constant kIOPMTimelineSystemBufferSizeKey
63 * @abstract Size in bytes  of buffer recording system PM events
64 * @discussion Key may be found in the dictionary at IOPMrootDomain's property
65 * kIOPMTimelineDictionaryKey. uint32_t value; may be 0.
66 */
67#define kIOPMTimelineSystemBufferSizeKey        "TimelineSystemBufferSize"
68
69
70
71/* @constant kIOPMEventTypeIntermediateFlag
72 * @abstract This bit indicates the event is an intermediate event
73 *      which must occur within a major system power event.
74 */
75#define kIOPMEventTypeIntermediateFlag              0x10000000
76
77/* @enum SystemEventTypes
78 * @abstract Potential system events logged in the system event record.
79 */
80enum {
81	kIOPMEventTypeUndefined                     = 0,
82
83    /* Event types mark driver events
84     */
85    kIOPMEventTypeSetPowerStateImmediate        = 1001,
86    kIOPMEventTypeSetPowerStateDelayed          = 1002,
87    kIOPMEventTypePSWillChangeTo                = 1003,
88    kIOPMEventTypePSDidChangeTo                 = 1004,
89    kIOPMEventTypeAppResponse                   = 1005,
90
91
92    /* Start and stop event types bracket major
93     * system power management events.
94     */
95	kIOPMEventTypeSleep                         = 2001,
96	kIOPMEventTypeSleepDone                     = 2002,
97	kIOPMEventTypeWake                          = 3001,
98	kIOPMEventTypeWakeDone                      = 3002,
99	kIOPMEventTypeDoze                          = 4001,
100	kIOPMEventTypeDozeDone                      = 4002,
101	kIOPMEventTypeLiteWakeUp                    = 5001,
102	kIOPMEventTypeLiteWakeUpDone                = 5002,
103	kIOPMEventTypeLiteWakeDown                  = 5003,
104	kIOPMEventTypeLiteWakeDownDone              = 5004,
105	kIOPMEventTypeUUIDSet                       = 6001,
106	kIOPMEventTypeUUIDClear                     = 6002,
107
108    /* Intermediate events that may only occur within the bounds
109     * of a major system event (between the event's initiation and its "done event".)
110     * e.g. chronologically kIOPMEventTypeSleep may be followed by one or more
111     *      intermediate events, which then must be followed by kIOPMEventTypeSleepDone.
112     *
113     * The intermediate events below will always occur in a Sleep or Wake event, and may
114     *      or may not occur for any of the other events.
115     */
116    kIOPMEventTypeAppNotificationsFinished      = 501 | kIOPMEventTypeIntermediateFlag,
117    kIOPMEventTypeDriverNotificationsFinished   = 502 | kIOPMEventTypeIntermediateFlag,
118    kIOPMEventTypeCalTimeChange                 = 503 | kIOPMEventTypeIntermediateFlag
119};
120
121
122/* @enum SystemSleepReasons
123 * @abstract The potential causes for system sleep as logged in the system event record.
124 */
125enum {
126    kIOPMSleepReasonClamshell                   = 101,
127    kIOPMSleepReasonPowerButton                 = 102,
128    kIOPMSleepReasonSoftware                    = 103,
129    kIOPMSleepReasonOSSwitchHibernate           = 104,
130    kIOPMSleepReasonIdle                        = 105,
131    kIOPMSleepReasonLowPower                    = 106,
132    kIOPMSleepReasonThermalEmergency            = 107,
133    kIOPMSleepReasonMaintenance                 = 108,
134    kIOPMSleepReasonSleepServiceExit            = 109,
135    kIOPMSleepReasonDarkWakeThermalEmergency    = 110
136};
137
138/*
139 * Possible C-string sleep reasons found under kRootDomainSleepReasonsKey
140 */
141#define kIOPMClamshellSleepKey                      "Clamshell Sleep"
142#define kIOPMPowerButtonSleepKey                    "Power Button Sleep"
143#define kIOPMSoftwareSleepKey                       "Software Sleep"
144#define kIOPMOSSwitchHibernationKey                 "OS Switch Sleep"
145#define kIOPMIdleSleepKey                           "Idle Sleep"
146#define kIOPMLowPowerSleepKey                       "Low Power Sleep"
147#define kIOPMThermalEmergencySleepKey               "Thermal Emergency Sleep"
148#define kIOPMSleepServiceExitKey                    "Sleep Service Back to Sleep"
149#define kIOPMDarkWakeThermalEmergencyKey            "Dark Wake Thermal Emergency"
150
151
152enum {
153    kIOPMMaxSystemEventsTracked = 25000,
154    kIOPMDefaultSystemEventsTracked = 1000,
155    kMaxPMStringLength = 40,
156};
157
158/* @struct IOPMSystemEventRecord
159 * @abstract Records a singe power event to a particular PM entity.
160 * This includes changes to a driver's power state, application responses
161 * to PM notifications, or system power management milestones.
162 */
163typedef struct {
164    union {
165        // For DRIVER events
166        char        ownerName[kMaxPMStringLength];
167        // For SYSTEM events, uuid contains the string describing the active UUID
168        char        uuid[kMaxPMStringLength];
169    };
170
171    // For DRIVER events - records the name of the driver who generated the notifications.
172    char        interestName[kMaxPMStringLength];
173
174    // DRIVER & SYSTEM - Times are stored as uint64_t
175    // The high 32 bytes are the seconds returned from clock_get_calendar_microtime,
176    // and the low 32 bytes are the accompanying microseconds.
177    uint64_t    timestamp;
178
179    union {
180        // For DRIVER events - ownerDisambiguateID is a unique descriptor of the driver, to disambiguate
181        // several similarly named drivers.
182        uint64_t    ownerDisambiguateID;
183        // For SYSTEM events - eventReason is a value in SystemSleepReason
184        uint64_t    eventReason;
185    };
186
187    // DRIVER & SYSTEM - eventType is one of 'SystemEventTypes'
188    // The value of eventType determines, among ohter things, whether this is a SYSTEM or
189    //      DRIVER event type.
190    uint32_t    eventType;
191
192    // DRIVER & SYSTEM - eventResult is an IOReturn value
193    uint32_t    eventResult;
194
195    // DRIVER - If defined, elapsedTimeUS records the entire time a transaction took to complete
196    uint32_t    elapsedTimeUS;
197
198    // DRIVER - in power state changes, oldState & newState are PM power state indices.
199    uint8_t     oldState;
200    uint8_t     newState;
201} IOPMSystemEventRecord;
202
203/* @struct IOPMTraceBufferHeader
204 * Occupies the first bytes in the buffer allocated by IOPMrootDomain
205 * Describes the size and current index of the trace buffer
206 */
207typedef struct {
208	uint32_t	sizeBytes;
209	uint32_t    sizeEntries;
210	uint32_t    index;
211} IOPMTraceBufferHeader;
212
213/* Argument to IOPMrootDomain::clientMemoryForType to acquire
214 * memory mapping.
215 */
216enum {
217    kPMRootDomainMapTraceBuffer = 1
218};
219
220/**************************************************
221*
222* Accountability API Ends here
223*
224**************************************************/
225
226
227#pragma mark Stray Bitfields
228// Private power commands issued to root domain
229// bits 0-7 in IOPM.h
230
231enum {
232    kIOPMSetValue                   = (1<<16),
233    // don't sleep on clamshell closure on a portable with AC connected
234    kIOPMSetDesktopMode             = (1<<17),
235    // set state of AC adaptor connected
236    kIOPMSetACAdaptorConnected      = (1<<18)
237};
238
239/*****************************************************************************/
240/*****************************************************************************/
241
242/*
243 * PM notification types
244 */
245
246/*! @constant kIOPMSleepServiceScheduleImmediate
247 *
248 * Setting type used in calls to IOPMrootDomain::registerPMSettingController
249 * Use this type between powerd and IOKit.framework
250 *
251 */
252#define kIOPMSleepServiceScheduleImmediate     "SleepServiceImmediate"
253
254/*! @constant kIOPMSettingSleepServiceScheduleImmediate
255 *
256 * Setting type used in calls to IOPMrootDomain::registerPMSettingController
257 * Use this type between xnu and AppleRTC
258 */
259#define kIOPMSettingSleepServiceWakeCalendarKey     "SleepServiceWakeCalendarKey"
260
261/*! @constant kIOPMCalendarWakeTypes
262 *
263 * These are valid values for IOPM.h:IOPMCalendarStruct->selector
264 */
265enum {
266    kPMCalendarTypeMaintenance = 1,
267    kPMCalendarTypeSleepService = 2
268};
269
270
271/* @constant kIOPMStateConsoleShutdown
272 * @abstract Notification of GUI shutdown state available to kexts.
273 * @discussion This type can be passed as arguments to registerPMSettingController()
274 * to receive callbacks.
275 */
276#define kIOPMStateConsoleShutdown   "ConsoleShutdown"
277
278/* @enum ShutdownValues
279 * @abstract Potential values shared with key kIOPMStateConsoleShutdown
280 */
281enum {
282/* @constant kIOPMStateConsoleShutdownNone
283 * @abstract System shutdown (or restart) hasn't started; system is ON.
284 * @discussion Next state: 2
285 */
286    kIOPMStateConsoleShutdownNone   = 1,
287/* @constant kIOPMStateConsoleShutdownPossible
288 * @abstract User has been presented with the option to shutdown or restart. Shutdown may be cancelled.
289 * @discussion Next state may be: 1, 4
290 */
291    kIOPMStateConsoleShutdownPossible = 2,
292/* @constant kIOPMStateConsoleShutdownUnderway
293 * @abstract Shutdown or restart is proceeding. It may still be cancelled.
294 * @discussion Next state may be: 1, 4. This state is currently unused.
295 */
296    kIOPMStateConsoleShutdownUnderway = 3,
297/* @constant kIOPMStateConsoleShutdownCertain
298 * @abstract Shutdown is in progress and irrevocable.
299 * @discussion State remains 4 until power is removed from CPU.
300 */
301    kIOPMStateConsoleShutdownCertain = 4
302};
303
304/* @constant kIOPMSettingSilentRunningKey
305 * @abstract Notification of silent running mode changes to kexts.
306 * @discussion This key can be passed as an argument to registerPMSettingController()
307 * and also identifies the type of PMSetting notification callback.
308 */
309#define kIOPMSettingSilentRunningKey    "SilentRunning"
310#define kIOPMFeatureSilentRunningKey    kIOPMSettingSilentRunningKey
311
312/* @enum SilentRunningFlags
313 * @abstract The kIOPMSettingSilentRunningKey notification provides an OSNumber
314 * object with a value described by the following flags.
315 */
316enum {
317    kIOPMSilentRunningModeOn = 0x00000001
318};
319
320/*****************************************************************************/
321/*****************************************************************************/
322
323/* PM Statistics - event indices
324 * These are arguments to IOPMrootDomain::pmStatsRecordEvent().
325 */
326enum {
327    kIOPMStatsHibernateImageWrite         = 1,
328    kIOPMStatsHibernateImageRead,
329    kIOPMStatsDriversNotify,
330    kIOPMStatsApplicationNotify,
331    kIOPMStatsLateDriverAcknowledge,
332    kIOPMStatsLateAppAcknowledge,
333
334    // To designate if you're specifying the start or stop end of
335    // each of the above events, do a bitwise OR of the appropriate
336    // Start/Stop flag and pass the result to IOPMrootDomain to record
337    // the event.
338    kIOPMStatsEventStartFlag              = (1 << 24),
339    kIOPMStatsEventStopFlag               = (1 << 25)
340};
341
342// Keys for IOPMrootDomain registry properties
343#define kIOPMSleepStatisticsKey                 "SleepStatistics"
344#define kIOPMSleepStatisticsAppsKey             "AppStatistics"
345
346// Application response statistics
347#define kIOPMStatsNameKey                       "Name"
348#define kIOPMStatsPIDKey                        "Pid"
349#define kIOPMStatsTimeMSKey                     "TimeMS"
350#define kIOPMStatsApplicationResponseTypeKey    "ResponseType"
351#define kIOPMStatsMessageTypeKey                "MessageType"
352
353// PM Statistics: potential values for the key kIOPMStatsApplicationResponseTypeKey
354// entry in the application results array.
355#define kIOPMStatsResponseTimedOut      "ResponseTimedOut"
356#define kIOPMStatsResponseCancel        "ResponseCancel"
357#define kIOPMStatsResponseSlow          "ResponseSlow"
358
359struct PMStatsBounds{
360    uint64_t start;
361    uint64_t stop;
362};
363typedef struct {
364
365    struct PMStatsBounds    hibWrite;
366    struct PMStatsBounds    hibRead;
367//    bounds    driverNotifySleep;
368//    bounds    driverNotifyWake;
369//    bounds    appNotifySleep;
370//    bounds    appNotifyWake;
371//    OSDictionary    *tardyApps;
372//    OSDictionary    *tardyDrivers;
373} PMStatsStruct;
374
375/*****************************************************************************/
376
377/* PM RootDomain tracePoints
378 *
379 * In the sleep/wake process, we expect the sleep trace points to proceed
380 * in increasing order. Once sleep begins with code kIOPMTracePointSleepStarted,
381 * we expect sleep to continue in a monotonically increasing order of tracepoints
382 * to kIOPMTracePointSystemLoginwindowPhase. After trace point SystemLoginWindowPhase,
383 * the system will return to kIOPMTracePointSystemUp.
384 *
385 * If the trace point decreases (instead of increasing) before reaching kIOPMTracePointSystemUp,
386 * that indicates that the sleep process was cancelled. The cancel reason shall be indicated
387 * in the cancel tracepoint. (TBD)
388 */
389
390enum {
391/* When kTracePointSystemUp is the latest tracePoint,
392 * the system is awake. It is not asleep, sleeping, or waking.
393 *
394 * Phase begins: At boot, at completion of wake from sleep,
395 *      immediately following kIOPMTracePointSystemLoginwindowPhase.
396 * Phase ends: When a sleep attempt is initiated.
397 */
398    kIOPMTracePointSystemUp                     = 0,
399
400/* When kIOPMTracePointSleepStarted is the latest tracePoint,
401 * sleep has been initiated.
402 *
403 * Phase begins: At initiation of system sleep (idle or forced).
404 * Phase ends: PM starts to notify applications of system sleep.
405 */
406    kIOPMTracePointSleepStarted                 = 0x10,
407
408/* When kIOPMTracePointSleepApplications is the latest tracePoint,
409 * a system sleep has been initiated and PM waits for responses
410 * from notified applications.
411 *
412 * Phase begins: Begin to asynchronously fire kIOMessageSystemWillSleep
413 *      notifications, and also kIOMessageCanSystemSleep for the idle sleep case.
414 * Phase ends: When PM has received all application responses.
415 */
416    kIOPMTracePointSleepApplications            = 0x11,
417
418/* When kIOPMTracePointSleepPriorityClients is the latest tracePoint,
419 * PM is notifying priority clients and in-kernel system capability
420 * clients, and waiting for any asynchronous completions.
421 *
422 * Phase begins: Synchronous delivery of kIOMessageSystemWillSleep notifications.
423 * Phase ends: All notified clients have acknowledged.
424 */
425    kIOPMTracePointSleepPriorityClients         = 0x12,
426
427/* When kIOPMTracePointSleepWillChangeInterests is the latest tracePoint,
428 * PM is calling powerStateWillChangeTo() on interested drivers of root domain.
429 *
430 * Phase begins: Dispatch a callout thread to call interested drivers.
431 * Phase ends: Callout thread work done, and acknowledgePowerChange() called
432 *      by drivers that indicated asynchronous completion.
433 */
434    kIOPMTracePointSleepWillChangeInterests     = 0x13,
435
436/* When kIOPMTracePointSleepPowerPlaneDrivers is the latest tracePoint,
437 * PM is directing power plane drivers to power off in leaf-to-root order.
438 *
439 * Phase begins: Root domain informs its power children that it will drop to
440 *      sleep state. This has a cascade effect and triggers all drivers in
441 *      the power plane to transition to a lower power state if necessary.
442 * Phase ends: All power transitions in response to the root domain power
443 *      change have completed.
444 */
445    kIOPMTracePointSleepPowerPlaneDrivers       = 0x14,
446
447/* When kIOPMTracePointSleepDidChangeInterests is the latest tracePoint,
448 * PM is calling powerStateDidChangeTo() on interested drivers of root domain.
449 *
450 * Phase begins: Dispatch a callout thread to call interested drivers.
451 * Phase ends: Callout thread work done, and acknowledgePowerChange() called
452 *      by drivers that indicated asynchronous completion.
453 */
454    kIOPMTracePointSleepDidChangeInterests      = 0x15,
455
456/* When kIOPMTracePointSleepCapabilityClients is the latest tracePoint,
457 * PM is notifying system capability clients about system sleep.
458 *
459 * Phase begins: Send kIOMessageSystemCapabilityChange notifications to inform
460 *      capability clients that system has lost all capabilities.
461 * Phase ends: Finished sending notifications.
462 */
463    kIOPMTracePointSleepCapabilityClients       = 0x16,
464
465/* When kIOPMTracePointSleepPlatformActions is the latest tracePoint,
466 * PM is calling drivers that have registered a platform sleep action.
467 */
468    kIOPMTracePointSleepPlatformActions         = 0x17,
469
470/* When kIOPMTracePointSleepCPUs is the latest tracePoint,
471 * PM is shutting down all non-boot processors.
472 *
473 * Phase begins: Shutdown all non-boot processors.
474 * Phase ends: Reduced to only the boot processor running.
475 */
476    kIOPMTracePointSleepCPUs                    = 0x18,
477
478/* When kIOPMTracePointSleepPlatformDriver is the latest tracePoint,
479 * PM is executing platform dependent code to prepare for system sleep.
480 */
481    kIOPMTracePointSleepPlatformDriver          = 0x19,
482
483/* When kIOPMTracePointHibernate is the latest tracePoint,
484 * PM is writing the hibernate image to disk.
485 */
486    kIOPMTracePointHibernate                    = 0x1a,
487
488/* When kIOPMTracePointSystemSleep is the latest tracePoint,
489 * PM has recorded the final trace point before the hardware platform
490 * enters sleep state, or low level wakeup is underway - such as restoring
491 * the hibernate image from disk.
492 *
493 * Note: If a system is asleep and then loses power, and it does not have a
494 * hibernate image to restore from (e.g. hibernatemode = 0), then OS X will
495 * interpret this power loss as a failure in kIOPMTracePointSystemSleep.
496 *
497 * Phase begins: Before the OS directs the hardware to enter sleep state.
498 * Phase ends: Control returns to the OS on wake, but before recording the first
499 *      wake trace point.
500 */
501    kIOPMTracePointSystemSleep                  = 0x1f,
502
503/* When kIOPMTracePointWakePlatformDriver is the latest tracePoint,
504 * PM is executing platform dependent code to prepare for system wake.
505 */
506    kIOPMTracePointWakePlatformDriver           = 0x21,
507
508/* When kIOPMTracePointWakePlatformActions is the latest tracePoint,
509 * PM is calling drivers that have registered a platform wake action.
510 */
511    kIOPMTracePointWakePlatformActions          = 0x22,
512
513/* When kIOPMTracePointWakeCPUs is the latest tracePoint,
514 * PM is bringing all non-boot processors online.
515 */
516    kIOPMTracePointWakeCPUs                     = 0x23,
517
518/* When kIOPMTracePointWakeWillPowerOnClients is the latest tracePoint,
519 * PM is sending kIOMessageSystemWillPowerOn to both kernel clients and
520 * applications. PM also notifies system capability clients about the
521 * proposed capability change.
522 *
523 * Phase begins: Send kIOMessageSystemWillPowerOn and
524 *      kIOMessageSystemCapabilityChange notifications.
525 * Phase ends: Finished sending notifications.
526 */
527    kIOPMTracePointWakeWillPowerOnClients       = 0x24,
528
529/* When kIOPMTracePointWakeWillChangeInterests is the latest tracePoint,
530 * PM is calling powerStateWillChangeTo() on interested drivers of root domain.
531 *
532 * Phase begins: Dispatch a callout thread to call interested drivers.
533 * Phase ends: Callout thread work done, and acknowledgePowerChange() called
534 *      by drivers that indicated asynchronous completion.
535 */
536    kIOPMTracePointWakeWillChangeInterests      = 0x25,
537
538/* When kIOPMTracePointWakeDidChangeInterests is the latest tracePoint,
539 * PM is calling powerStateDidChangeTo() on interested drivers of root domain.
540 *
541 * Phase begins: Dispatch a callout thread to call interested drivers.
542 * Phase ends: Callout thread work done, and acknowledgePowerChange() called
543 *      by drivers that indicated asynchronous completion.
544 */
545    kIOPMTracePointWakeDidChangeInterests       = 0x26,
546
547/* When kIOPMTracePointWakePowerPlaneDrivers is the latest tracePoint,
548 * PM is directing power plane drivers to power up in root-to-leaf order.
549 *
550 * Phase begins: Root domain informs its power children that it transitioned
551 *      to ON state. This has a cascade effect and triggers all drivers in
552 *      the power plane to re-evaluate and potentially change power state.
553 * Phase ends: All power transitions in response to the root domain power
554 *      change have completed.
555 */
556    kIOPMTracePointWakePowerPlaneDrivers        = 0x27,
557
558/* When kIOPMTracePointWakeCapabilityClients is the latest tracePoint,
559 * PM is notifying system capability clients about system wake, and waiting
560 * for any asynchronous completions.
561 *
562 * Phase begins: Inform capability clients that system has gained capabilities.
563 * Phase ends: All notified clients have acknowledged.
564 */
565    kIOPMTracePointWakeCapabilityClients        = 0x28,
566
567/* When kIOPMTracePointWakeApplications is the latest tracePoint,
568 * System CPU is powered, PM has powered on each driver.
569 *
570 * Phase begins: Send asynchronous kIOMessageSystemHasPoweredOn notifications.
571 * Phase ends: Finished sending asynchronous notifications.
572 */
573    kIOPMTracePointWakeApplications             = 0x29,
574
575/* kIOPMTracePointSystemLoginwindowPhase
576 * This phase represents a several minute window after the system has powered on.
577 * Higher levels of system diagnostics are in a heightened state of alert in this phase,
578 * in case any user errors occurred that we could not detect in software.
579 *
580 * Phase begins: After IOPMrootDomain sends kIOMessageSystemHasPoweredOn message.
581 * Phase ends: When loginwindow calls IOPMSleepWakeSetUUID(NULL) the system shall
582 *      be considered awake and usable. The next phase shall be kIOPMTracePointSystemUp.
583 */
584    kIOPMTracePointSystemLoginwindowPhase       = 0x30,
585
586/* When kIOPMTracePointDarkWakeEntry is the latest tracePoint,
587 * PM has started a transition from full wake to dark wake.
588 *
589 * Phase begins: Start transition to dark wake.
590 * Phase ends: System in dark wake. Before recording kIOPMTracePointSystemUp.
591 */
592    kIOPMTracePointDarkWakeEntry                = 0x31,
593
594/* When kIOPMTracePointDarkWakeExit is the latest tracePoint,
595 * PM has started a transition from dark wake to full wake.
596 *
597 * Phase begins: Start transition to full wake.
598 * Phase ends: System in full wake. Before recording kIOPMTracePointSystemUp.
599 */
600    kIOPMTracePointDarkWakeExit                 = 0x32
601};
602
603/*****************************************************************************/
604
605/*
606�* kIOPMLoginWindowSecurityDebugKey - identifies PM debug data specific to LoginWindow
607 *  for use with IOPMrootDomain.
608�*/
609#define kIOPMLoginWindowSecurityDebugKey        "LoginWindowSecurity"
610
611// For PM internal use only - key to locate sleep failure results within SCDynamicStore.
612#define kIOPMDynamicStoreSleepFailureKey        "SleepFailure"
613
614/*****************************************************************************/
615
616// For IOPMLibPrivate.h
617#define kIOPMSleepWakeFailureKey            "PMFailurePhase"
618#define kIOPMSleepWakeFailureCodeKey        "PMStatusCode"
619#define kIOPMSleepWakeFailureLoginKey       "LWFailurePhase"
620#define kIOPMSleepWakeFailureUUIDKey        "UUID"
621#define kIOPMSleepWakeFailureDateKey        "Date"
622
623/*****************************************************************************
624 *
625 * Root Domain private property keys
626 *
627 *****************************************************************************/
628
629/* kIOPMFeatureAutoPowerOffKey
630 * Feature published if Auto Power Off is supported
631 */
632#define kIOPMFeatureAutoPowerOffKey         "AutoPowerOff"
633
634/* kIOPMAutoPowerOffEnabledKey
635 * Indicates if Auto Power Off is enabled.
636 * It has a boolean value.
637 *  true        == Auto Power Off is enabled
638 *  false       == Auto Power Off is disabled
639 *  not present == Auto Power Off is not supported on this hardware
640 */
641#define kIOPMAutoPowerOffEnabledKey         "AutoPowerOff Enabled"
642
643/* kIOPMAutoPowerOffDelayKey
644 * Key refers to a CFNumberRef that represents the delay in seconds before
645 * entering the Auto Power Off state.  The property is not present if Auto
646 * Power Off is unsupported.
647 */
648#define kIOPMAutoPowerOffDelayKey           "AutoPowerOff Delay"
649
650/* kIOPMAutoPowerOffTimerKey
651 * Key refers to a CFNumberRef that indicates the time in seconds until the
652 * expiration of the Auto Power Off delay period. This value should be used
653 * to program a wake alarm before system sleep.
654 */
655#define kIOPMAutoPowerOffTimerKey           "AutoPowerOff Timer"
656
657/* kIOPMUserWakeAlarmScheduledKey
658 * Key refers to a boolean value that indicates if an user alarm was scheduled
659 * or pending.
660 */
661#define kIOPMUserWakeAlarmScheduledKey      "UserWakeAlarmScheduled"
662
663/*****************************************************************************
664 *
665 * System Sleep Policy
666 *
667 *****************************************************************************/
668
669#define kIOPMSystemSleepPolicySignature     0x54504c53
670#define kIOPMSystemSleepPolicyVersion       2
671
672/*!
673 * @defined kIOPMSystemSleepTypeKey
674 * @abstract Indicates the type of system sleep.
675 * @discussion An OSNumber property of root domain that describes the type
676 * of system sleep. This property is set after notifying priority sleep/wake
677 * clients, but before informing interested drivers and shutting down power
678 * plane drivers.
679 */
680#define kIOPMSystemSleepTypeKey             "IOPMSystemSleepType"
681
682struct IOPMSystemSleepPolicyVariables
683{
684    uint32_t    signature;                  // kIOPMSystemSleepPolicySignature
685    uint32_t    version;                    // kIOPMSystemSleepPolicyVersion
686
687    uint64_t    currentCapability;          // current system capability bits
688    uint64_t    highestCapability;          // highest system capability bits
689
690    uint64_t    sleepFactors;               // sleep factor bits
691    uint32_t    sleepReason;                // kIOPMSleepReason*
692    uint32_t    sleepPhase;                 // identify the sleep phase
693    uint32_t    hibernateMode;              // current hibernate mode
694
695    uint32_t    standbyDelay;               // standby delay in seconds
696    uint32_t    poweroffDelay;              // auto-poweroff delay in seconds
697    uint32_t    scheduledAlarms;            // bitmask of scheduled alarm types
698    uint32_t    poweroffTimer;              // auto-poweroff timer in seconds
699
700    uint32_t    reserved[49];               // pad sizeof 256 bytes
701};
702
703enum {
704    kIOPMAlarmBitDebugWake                  = 0x01,
705    kIOPMAlarmBitCalendarWake               = 0x02,
706    kIOPMAlarmBitMaintenanceWake            = 0x04,
707    kIOPMAlarmBitSleepServiceWake           = 0x08
708};
709
710enum {
711    kIOPMSleepPhase0 = 0,
712    kIOPMSleepPhase1,
713    kIOPMSleepPhase2
714};
715
716// Sleep Factor Mask / Bits
717enum {
718    kIOPMSleepFactorSleepTimerWake          = 0x00000001ULL,
719    kIOPMSleepFactorLidOpen                 = 0x00000002ULL,
720    kIOPMSleepFactorACPower                 = 0x00000004ULL,
721    kIOPMSleepFactorBatteryLow              = 0x00000008ULL,
722    kIOPMSleepFactorStandbyNoDelay          = 0x00000010ULL,
723    kIOPMSleepFactorStandbyForced           = 0x00000020ULL,
724    kIOPMSleepFactorStandbyDisabled         = 0x00000040ULL,
725    kIOPMSleepFactorUSBExternalDevice       = 0x00000080ULL,
726    kIOPMSleepFactorBluetoothHIDDevice      = 0x00000100ULL,
727    kIOPMSleepFactorExternalMediaMounted    = 0x00000200ULL,
728    kIOPMSleepFactorThunderboltDevice       = 0x00000400ULL,
729    kIOPMSleepFactorRTCAlarmScheduled       = 0x00000800ULL,
730    kIOPMSleepFactorMagicPacketWakeEnabled  = 0x00001000ULL,
731    kIOPMSleepFactorHibernateForced         = 0x00010000ULL,
732    kIOPMSleepFactorAutoPowerOffDisabled    = 0x00020000ULL,
733    kIOPMSleepFactorAutoPowerOffForced      = 0x00040000ULL,
734    kIOPMSleepFactorExternalDisplay         = 0x00080000ULL
735};
736
737// System Sleep Types
738enum {
739    kIOPMSleepTypeInvalid                   = 0,
740    kIOPMSleepTypeAbortedSleep              = 1,
741    kIOPMSleepTypeNormalSleep               = 2,
742    kIOPMSleepTypeSafeSleep                 = 3,
743    kIOPMSleepTypeHibernate                 = 4,
744    kIOPMSleepTypeStandby                   = 5,
745    kIOPMSleepTypePowerOff                  = 6,
746    kIOPMSleepTypeLast                      = 7
747};
748
749// System Sleep Flags
750enum {
751    kIOPMSleepFlagDisableHibernateAbort     = 0x00000001,
752    kIOPMSleepFlagDisableUSBWakeEvents      = 0x00000002,
753    kIOPMSleepFlagDisableBatlowAssertion    = 0x00000004
754};
755
756// System Wake Events
757enum {
758    kIOPMWakeEventLidOpen                   = 0x00000001,
759    kIOPMWakeEventLidClose                  = 0x00000002,
760    kIOPMWakeEventACAttach                  = 0x00000004,
761    kIOPMWakeEventACDetach                  = 0x00000008,
762    kIOPMWakeEventCDInsert                  = 0x00000010,
763    kIOPMWakeEventCDEject                   = 0x00000020,
764    kIOPMWakeEventHPDAttach                 = 0x00000040,
765    kIOPMWakeEventHPDDetach                 = 0x00000080,
766    kIOPMWakeEventPowerButton               = 0x00000100,
767    kIOPMWakeEventG3PowerOn                 = 0x00000200,
768    kIOPMWakeEventUserPME                   = 0x00000400,
769    kIOPMWakeEventSleepTimer                = 0x00000800,
770    kIOPMWakeEventBatteryLow                = 0x00001000,
771    kIOPMWakeEventDarkPME                   = 0x00002000
772};
773
774/*!
775 * @defined kIOPMSystemSleepParametersKey
776 * @abstract Sleep parameters describing the upcoming sleep
777 * @discussion Root domain updates this OSData property before system sleep
778 * to pass sleep parameters to the platform driver.  Some of the parameters
779 * are based on the chosen entry in the system sleep policy table.
780 */
781#define kIOPMSystemSleepParametersKey       "IOPMSystemSleepParameters"
782#define kIOPMSystemSleepParametersVersion   2
783
784struct IOPMSystemSleepParameters
785{
786    uint16_t    version;
787    uint16_t    reserved1;
788    uint32_t    sleepType;
789    uint32_t    sleepFlags;
790    uint32_t    ecWakeEvents;
791    uint32_t    ecWakeTimer;
792    uint32_t    ecPoweroffTimer;
793    uint32_t    reserved2[10];
794} __attribute__((packed));
795
796#if defined(KERNEL) && defined(__cplusplus)
797
798/*!
799 * @defined kIOPMInstallSystemSleepPolicyHandlerKey
800 * @abstract Name of the platform function to install a sleep policy handler.
801 * @discussion Pass to IOPMrootDomain::callPlatformFunction(), with a pointer
802 * to the C-function handler at param1, and an optional target at param2, to
803 * register a sleep policy handler. Only a single sleep policy handler can
804 * be installed.
805 */
806#define kIOPMInstallSystemSleepPolicyHandlerKey	\
807        "IOPMInstallSystemSleepPolicyHandler"
808
809typedef IOReturn (*IOPMSystemSleepPolicyHandler)(
810        void * target,
811        const IOPMSystemSleepPolicyVariables * vars,
812        IOPMSystemSleepParameters * params );
813
814#endif /* KERNEL */
815
816#endif /* ! _IOKIT_IOPMPRIVATE_H */
817