iokit/Kernel/IOServicePMPrivate.h

   1 /*
   2  * Copyright (c) 2019 Apple 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 #ifndef _IOKIT_IOSERVICEPMPRIVATE_H
  30 #define _IOKIT_IOSERVICEPMPRIVATE_H
  31
  32 #include <IOKit/IOCommand.h>
  33 #include <IOKit/IOEventSource.h>
  34
  35 //******************************************************************************
  36 // PM command types
  37 //******************************************************************************
  38
  39 enum {
  40         /* Command Types */
  41         kIOPMRequestTypeInvalid                     = 0x00,
  42         kIOPMRequestTypePMStop                      = 0x01,
  43         kIOPMRequestTypeAddPowerChild1              = 0x02,
  44         kIOPMRequestTypeAddPowerChild2              = 0x03,
  45         kIOPMRequestTypeAddPowerChild3              = 0x04,
  46         kIOPMRequestTypeRegisterPowerDriver         = 0x05,
  47         kIOPMRequestTypeAdjustPowerState            = 0x06,
  48         kIOPMRequestTypePowerDomainWillChange       = 0x07,
  49         kIOPMRequestTypePowerDomainDidChange        = 0x08,
  50         kIOPMRequestTypePowerOverrideOnPriv         = 0x09,
  51         kIOPMRequestTypePowerOverrideOffPriv        = 0x0A,
  52         kIOPMRequestTypeActivityTickle              = 0x0B,
  53         kIOPMRequestTypeRequestPowerState           = 0x0C,
  54         kIOPMRequestTypeSynchronizePowerTree        = 0x0D,
  55         kIOPMRequestTypeRequestPowerStateOverride   = 0x0E,
  56         kIOPMRequestTypeSetIdleTimerPeriod          = 0x0F,
  57         kIOPMRequestTypeIgnoreIdleTimer             = 0x10,
  58         kIOPMRequestTypeQuiescePowerTree            = 0x11,
  59
  60         /* Reply Types */
  61         kIOPMRequestTypeReplyStart                  = 0x80,
  62         kIOPMRequestTypeAckPowerChange              = 0x81,
  63         kIOPMRequestTypeAckSetPowerState            = 0x82,
  64         kIOPMRequestTypeAllowPowerChange            = 0x83,
  65         kIOPMRequestTypeCancelPowerChange           = 0x84,
  66         kIOPMRequestTypeInterestChanged             = 0x85,
  67         kIOPMRequestTypeIdleCancel                  = 0x86,
  68         kIOPMRequestTypeChildNotifyDelayCancel      = 0x87
  69 };
  70
  71 //******************************************************************************
  72 // PM actions - For root domain only
  73 //******************************************************************************
  74
  75 struct IOPMActions;
  76
  77 typedef void
  78 (*IOPMActionPowerChangeStart)(
  79         void *                  target,
  80         IOService *             service,
  81         IOPMActions *           actions,
  82         IOPMPowerStateIndex     powerState,
  83         IOPMPowerChangeFlags *  changeFlags,
  84         IOPMRequestTag          requestTag );
  85
  86 typedef void
  87 (*IOPMActionPowerChangeDone)(
  88         void *                  target,
  89         IOService *             service,
  90         IOPMActions *           actions,
  91         IOPMPowerStateIndex     powerState,
  92         IOPMPowerChangeFlags    changeFlags,
  93         IOPMRequestTag          requestTag );
  94
  95 typedef void
  96 (*IOPMActionPowerChangeOverride)(
  97         void *                  target,
  98         IOService *             service,
  99         IOPMActions *           actions,
 100         IOPMPowerStateIndex *   powerState,
 101         IOPMPowerChangeFlags *  changeFlags,
 102         IOPMRequestTag          requestTag );
 103
 104 typedef void
 105 (*IOPMActionActivityTickle)(
 106         void *                  target,
 107         IOService *             service,
 108         IOPMActions *           actions );
 109
 110 typedef void
 111 (*IOPMActionUpdatePowerClient)(
 112         void *                  target,
 113         IOService *             service,
 114         IOPMActions *           actions,
 115         const OSSymbol *        powerClient,
 116         IOPMPowerStateIndex     oldPowerState,
 117         IOPMPowerStateIndex     newPowerState
 118         );
 119
 120 struct IOPMActions {
 121         void *                          target;
 122         uint32_t                        parameter;
 123         IOPMActionPowerChangeStart      actionPowerChangeStart;
 124         IOPMActionPowerChangeDone       actionPowerChangeDone;
 125         IOPMActionPowerChangeOverride   actionPowerChangeOverride;
 126         IOPMActionActivityTickle        actionActivityTickle;
 127         IOPMActionUpdatePowerClient     actionUpdatePowerClient;
 128 };
 129
 130 // IOPMActions parameter flags
 131 enum {
 132         kPMActionsFlagIsDisplayWrangler = 0x00000100,
 133         kPMActionsFlagIsGraphicsDevice  = 0x00000200,
 134         kPMActionsFlagIsAudioDevice     = 0x00000400,
 135         kPMActionsFlagLimitPower        = 0x00000800,
 136         kPMActionsPCIBitNumberMask      = 0x000000ff
 137 };
 138
 139 //******************************************************************************
 140 // Internal concise representation of IOPMPowerState
 141 struct IOPMPSEntry {
 142         IOPMPowerFlags      capabilityFlags;
 143         IOPMPowerFlags      outputPowerFlags;
 144         IOPMPowerFlags      inputPowerFlags;
 145         uint32_t            staticPower;
 146         uint32_t            settleUpTime;
 147         uint32_t            settleDownTime;
 148         IOPMPowerStateIndex stateOrder;
 149         IOPMPowerStateIndex stateOrderToIndex;
 150 };
 151
 152 //******************************************************************************
 153 // IOServicePM
 154 //******************************************************************************
 155
 156 class IOServicePM : public OSObject
 157 {
 158         friend class IOService;
 159         friend class IOPMWorkQueue;
 160
 161         OSDeclareDefaultStructors( IOServicePM );
 162
 163 private:
 164 // Link IOServicePM objects on IOPMWorkQueue.
 165         queue_chain_t           WorkChain;
 166
 167 // Queue of IOPMRequest objects.
 168         queue_head_t            RequestHead;
 169
 170 // IOService creator and owner.
 171         IOService *             Owner;
 172
 173 // List of interested drivers (protected by PMLock).
 174         IOPMinformeeList *      InterestedDrivers;
 175
 176 // How long to wait for controlling driver to acknowledge.
 177         IOReturn                DriverTimer;
 178
 179 // Current power management machine state.
 180         uint32_t                MachineState;
 181
 182         thread_call_t           AckTimer;
 183         thread_call_t           SettleTimer;
 184         thread_call_t           IdleTimer;
 185         thread_call_t           WatchdogTimer;
 186         thread_call_t           SpinDumpTimer;
 187
 188         IOLock  *               WatchdogLock;
 189         OSArray *               BlockedArray;
 190         uint64_t                PendingResponseDeadline;
 191         uint64_t                WatchdogDeadline;
 192
 193 // Settle time after changing power state.
 194         uint32_t                SettleTimeUS;
 195         uint32_t                IdleTimerGeneration;
 196
 197 // The flags describing current change note.
 198         IOPMPowerChangeFlags    HeadNoteChangeFlags;
 199
 200 // The new power state number being changed to.
 201         IOPMPowerStateIndex     HeadNotePowerState;
 202
 203 // Points to the entry in the power state array.
 204         IOPMPSEntry *           HeadNotePowerArrayEntry;
 205
 206 // Power flags supplied by all parents (domain).
 207         IOPMPowerFlags          HeadNoteDomainFlags;
 208
 209 // Power flags supplied by domain accounting for parent changes.
 210         IOPMPowerFlags          HeadNoteDomainTargetFlags;
 211
 212 // Connection attached to the changing parent.
 213         IOPowerConnection *     HeadNoteParentConnection;
 214
 215 // Power flags supplied by the changing parent.
 216         IOPMPowerFlags          HeadNoteParentFlags;
 217
 218 // Number of acks still outstanding.
 219         uint32_t                HeadNotePendingAcks;
 220
 221 // PM state lock.
 222         IOLock *                PMLock;
 223
 224         unsigned int            InitialPowerChange          :1;
 225         unsigned int            InitialSetPowerState        :1;
 226         unsigned int            DeviceOverrideEnabled       :1;
 227         unsigned int            DoNotPowerDown              :1;
 228         unsigned int            ParentsKnowState            :1;
 229         unsigned int            StrictTreeOrder             :1;
 230         unsigned int            IdleTimerStopped            :1;
 231         unsigned int            AdjustPowerScheduled        :1;
 232
 233         unsigned int            IsPreChange                 :1;
 234         unsigned int            DriverCallBusy              :1;
 235         unsigned int            PCDFunctionOverride         :1;
 236         unsigned int            IdleTimerIgnored            :1;
 237         unsigned int            HasAdvisoryDesire           :1;
 238         unsigned int            AdvisoryTickleUsed          :1;
 239         unsigned int            ResetPowerStateOnWake       :1;
 240
 241 // Time of last device activity.
 242         AbsoluteTime            DeviceActiveTimestamp;
 243         AbsoluteTime            MaxPowerStateEntryTime;
 244         AbsoluteTime            MaxPowerStateExitTime;
 245
 246 // Used to protect activity flag.
 247         IOLock *                ActivityLock;
 248
 249 // Idle timer's period in seconds.
 250         unsigned long           IdleTimerPeriod;
 251         unsigned long           IdleTimerMinPowerState;
 252         unsigned long           NextIdleTimerPeriod;
 253         AbsoluteTime            IdleTimerStartTime;
 254
 255 // Power state desired by a subclassed device object.
 256         IOPMPowerStateIndex     DeviceDesire;
 257
 258 // This is the power state we desire currently.
 259         IOPMPowerStateIndex     DesiredPowerState;
 260
 261 // This is what our parent thinks our need is.
 262         IOPMPowerFlags          PreviousRequestPowerFlags;
 263
 264 // Cache result from getName(), used in logging.
 265         const char *            Name;
 266
 267 // Number of power states in the power array.
 268         IOPMPowerStateIndex     NumberOfPowerStates;
 269
 270 // Ordered highest power state in the power array.
 271         IOPMPowerStateIndex     HighestPowerState;
 272
 273 // Power state array.
 274         IOPMPSEntry *           PowerStates;
 275
 276 // The controlling driver.
 277         IOService *             ControllingDriver;
 278
 279 // Our current power state.
 280         IOPMPowerStateIndex     CurrentPowerState;
 281
 282 // Logical OR of power flags for each power domain parent.
 283         IOPMPowerFlags          ParentsCurrentPowerFlags;
 284
 285 // The highest power state we can achieve in current power domain.
 286         IOPMPowerStateIndex     MaxPowerState;
 287
 288 // Logical OR of all output power flags in the power state array.
 289         IOPMPowerFlags          MergedOutputPowerFlags;
 290
 291 // OSArray which manages responses from notified apps and clients.
 292         OSArray *               ResponseArray;
 293         OSArray *               NotifyClientArray;
 294
 295 // Used to uniquely identify power management notification to apps and clients.
 296         UInt16                  SerialNumber;
 297
 298 // Used to communicate desired function to tellClientsWithResponse().
 299 // This is used because it avoids changing the signatures of the affected virtual methods.
 300         int                     OutOfBandParameter;
 301
 302         AbsoluteTime            DriverCallStartTime;
 303         IOPMPowerFlags          CurrentCapabilityFlags;
 304         unsigned long           CurrentPowerConsumption;
 305         IOPMPowerStateIndex     TempClampPowerState;
 306         OSArray *               NotifyChildArray;
 307         OSDictionary *          PowerClients;
 308         thread_call_t           DriverCallEntry;
 309         void *                  DriverCallParamPtr;
 310         IOItemCount             DriverCallParamCount;
 311         IOItemCount             DriverCallParamSlots;
 312         uint32_t                DriverCallReason;
 313         uint32_t                OutOfBandMessage;
 314         uint32_t                TempClampCount;
 315         uint32_t                OverrideMaxPowerState;
 316         uint32_t                DeviceUsablePowerState;
 317
 318 // Protected by ActivityLock - BEGIN
 319         IOPMPowerStateIndex     ActivityTicklePowerState;
 320         IOPMPowerStateIndex     AdvisoryTicklePowerState;
 321         uint32_t                ActivityTickleCount;
 322         uint32_t                DeviceWasActive     : 1;
 323         uint32_t                AdvisoryTickled     : 1;
 324 // Protected by ActivityLock - END
 325
 326         uint32_t                WaitReason;
 327         uint32_t                SavedMachineState;
 328
 329 // Protected by PMLock - BEGIN
 330         struct {
 331                 uint32_t            PMStop              : 1;
 332                 uint32_t            PMDriverCallWait    : 1;
 333         } LockedFlags;
 334
 335         queue_head_t            PMDriverCallQueue;
 336         OSSet *                 InsertInterestSet;
 337         OSSet *                 RemoveInterestSet;
 338
 339 // IOReporter Data
 340         uint32_t                ReportClientCnt;
 341         void *                  ReportBuf;
 342 // Protected by PMLock - END
 343
 344 #if PM_VARS_SUPPORT
 345         IOPMprot *              PMVars;
 346 #endif
 347
 348         IOPMActions             PMActions;
 349
 350 // Serialize IOServicePM state for debug output.
 351         IOReturn gatedSerialize( OSSerialize * s ) const;
 352         virtual bool serialize( OSSerialize * s ) const APPLE_KEXT_OVERRIDE;
 353
 354 // PM log and trace
 355         void pmPrint( uint32_t event, uintptr_t param1, uintptr_t param2 ) const;
 356         void pmTrace( uint32_t event, uint32_t eventFunc, uintptr_t param1, uintptr_t param2 ) const;
 357 };
 358
 359 #define fOwner                      pwrMgt->Owner
 360 #define fInterestedDrivers          pwrMgt->InterestedDrivers
 361 #define fDriverTimer                pwrMgt->DriverTimer
 362 #define fMachineState               pwrMgt->MachineState
 363 #define fAckTimer                   pwrMgt->AckTimer
 364 #define fSettleTimer                pwrMgt->SettleTimer
 365 #define fIdleTimer                  pwrMgt->IdleTimer
 366 #define fWatchdogTimer              pwrMgt->WatchdogTimer
 367 #define fWatchdogDeadline           pwrMgt->WatchdogDeadline
 368 #define fWatchdogLock               pwrMgt->WatchdogLock
 369 #define fBlockedArray               pwrMgt->BlockedArray
 370 #define fPendingResponseDeadline    pwrMgt->PendingResponseDeadline
 371 #define fSettleTimeUS               pwrMgt->SettleTimeUS
 372 #define fIdleTimerGeneration        pwrMgt->IdleTimerGeneration
 373 #define fHeadNoteChangeFlags        pwrMgt->HeadNoteChangeFlags
 374 #define fHeadNotePowerState         pwrMgt->HeadNotePowerState
 375 #define fHeadNotePowerArrayEntry    pwrMgt->HeadNotePowerArrayEntry
 376 #define fHeadNoteDomainFlags        pwrMgt->HeadNoteDomainFlags
 377 #define fHeadNoteDomainTargetFlags  pwrMgt->HeadNoteDomainTargetFlags
 378 #define fHeadNoteParentConnection   pwrMgt->HeadNoteParentConnection
 379 #define fHeadNoteParentFlags        pwrMgt->HeadNoteParentFlags
 380 #define fHeadNotePendingAcks        pwrMgt->HeadNotePendingAcks
 381 #define fPMLock                     pwrMgt->PMLock
 382 #define fInitialPowerChange         pwrMgt->InitialPowerChange
 383 #define fInitialSetPowerState       pwrMgt->InitialSetPowerState
 384 #define fDeviceOverrideEnabled      pwrMgt->DeviceOverrideEnabled
 385 #define fDoNotPowerDown             pwrMgt->DoNotPowerDown
 386 #define fParentsKnowState           pwrMgt->ParentsKnowState
 387 #define fStrictTreeOrder            pwrMgt->StrictTreeOrder
 388 #define fIdleTimerStopped           pwrMgt->IdleTimerStopped
 389 #define fAdjustPowerScheduled       pwrMgt->AdjustPowerScheduled
 390 #define fIsPreChange                pwrMgt->IsPreChange
 391 #define fDriverCallBusy             pwrMgt->DriverCallBusy
 392 #define fPCDFunctionOverride        pwrMgt->PCDFunctionOverride
 393 #define fIdleTimerIgnored           pwrMgt->IdleTimerIgnored
 394 #define fHasAdvisoryDesire          pwrMgt->HasAdvisoryDesire
 395 #define fAdvisoryTickleUsed         pwrMgt->AdvisoryTickleUsed
 396 #define fResetPowerStateOnWake      pwrMgt->ResetPowerStateOnWake
 397 #define fDeviceActiveTimestamp      pwrMgt->DeviceActiveTimestamp
 398 #define fMaxPowerStateEntryTime     pwrMgt->MaxPowerStateEntryTime
 399 #define fMaxPowerStateExitTime      pwrMgt->MaxPowerStateExitTime
 400 #define fActivityLock               pwrMgt->ActivityLock
 401 #define fIdleTimerPeriod            pwrMgt->IdleTimerPeriod
 402 #define fIdleTimerMinPowerState     pwrMgt->IdleTimerMinPowerState
 403 #define fNextIdleTimerPeriod        pwrMgt->NextIdleTimerPeriod
 404 #define fIdleTimerStartTime         pwrMgt->IdleTimerStartTime
 405 #define fDeviceDesire               pwrMgt->DeviceDesire
 406 #define fDesiredPowerState          pwrMgt->DesiredPowerState
 407 #define fPreviousRequestPowerFlags  pwrMgt->PreviousRequestPowerFlags
 408 #define fName                       pwrMgt->Name
 409 #define fNumberOfPowerStates        pwrMgt->NumberOfPowerStates
 410 #define fHighestPowerState          pwrMgt->HighestPowerState
 411 #define fPowerStates                pwrMgt->PowerStates
 412 #define fControllingDriver          pwrMgt->ControllingDriver
 413 #define fCurrentPowerState          pwrMgt->CurrentPowerState
 414 #define fParentsCurrentPowerFlags   pwrMgt->ParentsCurrentPowerFlags
 415 #define fMaxPowerState              pwrMgt->MaxPowerState
 416 #define fMergedOutputPowerFlags     pwrMgt->MergedOutputPowerFlags
 417 #define fResponseArray              pwrMgt->ResponseArray
 418 #define fNotifyClientArray          pwrMgt->NotifyClientArray
 419 #define fSerialNumber               pwrMgt->SerialNumber
 420 #define fOutOfBandParameter         pwrMgt->OutOfBandParameter
 421 #define fDriverCallStartTime        pwrMgt->DriverCallStartTime
 422 #define fCurrentCapabilityFlags     pwrMgt->CurrentCapabilityFlags
 423 #define fCurrentPowerConsumption    pwrMgt->CurrentPowerConsumption
 424 #define fTempClampPowerState        pwrMgt->TempClampPowerState
 425 #define fNotifyChildArray           pwrMgt->NotifyChildArray
 426 #define fPowerClients               pwrMgt->PowerClients
 427 #define fDriverCallEntry            pwrMgt->DriverCallEntry
 428 #define fDriverCallParamPtr         pwrMgt->DriverCallParamPtr
 429 #define fDriverCallParamCount       pwrMgt->DriverCallParamCount
 430 #define fDriverCallParamSlots       pwrMgt->DriverCallParamSlots
 431 #define fDriverCallReason           pwrMgt->DriverCallReason
 432 #define fOutOfBandMessage           pwrMgt->OutOfBandMessage
 433 #define fTempClampCount             pwrMgt->TempClampCount
 434 #define fOverrideMaxPowerState      pwrMgt->OverrideMaxPowerState
 435 #define fDeviceUsablePowerState     pwrMgt->DeviceUsablePowerState
 436 #define fActivityTicklePowerState   pwrMgt->ActivityTicklePowerState
 437 #define fAdvisoryTicklePowerState   pwrMgt->AdvisoryTicklePowerState
 438 #define fActivityTickleCount        pwrMgt->ActivityTickleCount
 439 #define fDeviceWasActive            pwrMgt->DeviceWasActive
 440 #define fAdvisoryTickled            pwrMgt->AdvisoryTickled
 441 #define fWaitReason                 pwrMgt->WaitReason
 442 #define fSavedMachineState          pwrMgt->SavedMachineState
 443 #define fLockedFlags                pwrMgt->LockedFlags
 444 #define fPMDriverCallQueue          pwrMgt->PMDriverCallQueue
 445 #define fInsertInterestSet          pwrMgt->InsertInterestSet
 446 #define fRemoveInterestSet          pwrMgt->RemoveInterestSet
 447 #define fReportClientCnt            pwrMgt->ReportClientCnt
 448 #define fReportBuf                  pwrMgt->ReportBuf
 449 #define fPMVars                     pwrMgt->PMVars
 450 #define fPMActions                  pwrMgt->PMActions
 451
 452 #define StateOrder(state)           (((state) < fNumberOfPowerStates)               \
 453                                     ? pwrMgt->PowerStates[(state)].stateOrder       \
 454                                     : (state))
 455 #define StateMax(a, b)               (StateOrder((a)) < StateOrder((b)) ? (b) : (a))
 456 #define StateMin(a, b)               (StateOrder((a)) < StateOrder((b)) ? (a) : (b))
 457
 458 #define kPowerStateZero             (0)
 459
 460 /*
 461  *  When an IOService is waiting for acknowledgement to a power change
 462  *  notification from an interested driver or the controlling driver,
 463  *  the ack timer is ticking every tenth of a second.
 464  *  (100000000 nanoseconds are one tenth of a second).
 465  */
 466 #define ACK_TIMER_PERIOD            100000000
 467
 468 #if defined(__i386__) || defined(__x86_64__)
 469 #define WATCHDOG_SLEEP_TIMEOUT      (180)   // 180 secs
 470 #define WATCHDOG_WAKE_TIMEOUT       (180)   // 180  secs
 471 #else
 472 #define WATCHDOG_SLEEP_TIMEOUT      (180)   // 180 secs
 473 #define WATCHDOG_WAKE_TIMEOUT       (180)   // 180 secs
 474 #endif
 475
 476 // Max wait time in microseconds for kernel priority and capability clients
 477 // with async message handlers to acknowledge.
 478 //
 479 #define kPriorityClientMaxWait      (90 * 1000 * 1000)
 480 #define kCapabilityClientMaxWait    (240 * 1000 * 1000)
 481
 482 // Attributes describing a power state change.
 483 // See IOPMPowerChangeFlags data type.
 484 //
 485 #define kIOPMParentInitiated        0x0001  // power change initiated by our  parent
 486 #define kIOPMSelfInitiated          0x0002  // power change initiated by this device
 487 #define kIOPMNotDone                0x0004  // we couldn't make this change
 488 #define kIOPMDomainWillChange       0x0008  // change started by PowerDomainWillChangeTo
 489 #define kIOPMDomainDidChange        0x0010  // change started by PowerDomainDidChangeTo
 490 #define kIOPMDomainPowerDrop        0x0020  // Domain is lowering power
 491 #define kIOPMIgnoreChildren         0x0040  // Ignore children and driver power desires
 492 #define kIOPMSkipAskPowerDown       0x0080  // skip the ask app phase
 493 #define kIOPMSynchronize            0x0100  // change triggered by power tree re-sync
 494 #define kIOPMSyncNoChildNotify      0x0200  // sync root domain only, not entire tree
 495 #define kIOPMSyncTellPowerDown      0x0400  // send the ask/will power off messages
 496 #define kIOPMSyncCancelPowerDown    0x0800  // sleep cancel for maintenance wake
 497 #define kIOPMInitialPowerChange     0x1000  // set for initial power change
 498 #define kIOPMRootChangeUp           0x2000  // Root power domain change up
 499 #define kIOPMRootChangeDown         0x4000  // Root power domain change down
 500 #define kIOPMExpireIdleTimer        0x8000  // Accelerate idle timer expiration
 501
 502 #define kIOPMRootBroadcastFlags     (kIOPMSynchronize  | \
 503                                      kIOPMRootChangeUp | kIOPMRootChangeDown)
 504
 505 // Activity tickle request flags
 506 #define kTickleTypePowerDrop        0x01
 507 #define kTickleTypePowerRise        0x02
 508 #define kTickleTypeActivity         0x04
 509 #define kTickleTypeAdvisory         0x08
 510
 511 enum {
 512         kDriverCallInformPreChange,
 513         kDriverCallInformPostChange,
 514         kDriverCallSetPowerState,
 515         kRootDomainInformPreChange
 516 };
 517
 518 struct DriverCallParam {
 519         OSObject *  Target;
 520         IOReturn    Result;
 521 };
 522
 523 // values of OutOfBandParameter
 524 enum {
 525         kNotifyApps,
 526         kNotifyPriority,
 527         kNotifyCapabilityChangeApps,
 528         kNotifyCapabilityChangePriority
 529 };
 530
 531 typedef bool (*IOPMMessageFilter)(
 532         void * target, void * object, void * arg1, void * arg2, void * arg3 );
 533
 534 // used for applyToInterested
 535 struct IOPMInterestContext {
 536         OSArray *               responseArray;
 537         OSArray *               notifyClients;
 538         uint16_t                serialNumber;
 539         uint8_t                 isPreChange;
 540         uint8_t                 enableTracing;
 541         uint32_t                maxTimeRequested;
 542         uint32_t                messageType;
 543         uint32_t                notifyType;
 544         uint32_t                skippedInDark;
 545         uint32_t                notSkippedInDark;
 546         IOService *             us;
 547         IOPMPowerStateIndex     stateNumber;
 548         IOPMPowerFlags          stateFlags;
 549         IOPMPowerChangeFlags    changeFlags;
 550         const char *            errorLog;
 551         IOPMMessageFilter       messageFilter;
 552 };
 553
 554 // assertPMDriverCall() options
 555 enum {
 556         kIOPMDriverCallNoInactiveCheck = 1
 557 };
 558
 559 // assertPMDriverCall() method
 560 enum {
 561         kIOPMDriverCallMethodUnknown       = 0,
 562         kIOPMDriverCallMethodSetPowerState = 1,
 563         kIOPMDriverCallMethodWillChange    = 2,
 564         kIOPMDriverCallMethodDidChange     = 3,
 565         kIOPMDriverCallMethodChangeDone    = 4,
 566         kIOPMDriverCallMethodSetAggressive = 5
 567 };
 568
 569 //******************************************************************************
 570 // PM Statistics & Diagnostics
 571 //******************************************************************************
 572
 573 extern const OSSymbol *gIOPMStatsResponseTimedOut;
 574 extern const OSSymbol *gIOPMStatsResponseCancel;
 575 extern const OSSymbol *gIOPMStatsResponseSlow;
 576 extern const OSSymbol *gIOPMStatsResponsePrompt;
 577 extern const OSSymbol *gIOPMStatsDriverPSChangeSlow;
 578
 579 //******************************************************************************
 580 // IOPMRequest
 581 //******************************************************************************
 582
 583 class IOPMRequest : public IOCommand
 584 {
 585         OSDeclareDefaultStructors( IOPMRequest );
 586
 587 protected:
 588         IOService *          fTarget;       // request target
 589         IOPMRequest *        fRequestNext;  // the next request in the chain
 590         IOPMRequest *        fRequestRoot;  // the root request in the call tree
 591         IOItemCount          fWorkWaitCount;// execution blocked if non-zero
 592         IOItemCount          fFreeWaitCount;// completion blocked if non-zero
 593         uint32_t             fRequestType;  // request type
 594         bool                 fIsQuiesceBlocker;
 595
 596         IOPMCompletionAction fCompletionAction;
 597         void *               fCompletionTarget;
 598         void *               fCompletionParam;
 599
 600 public:
 601         uint32_t             fRequestTag;
 602         void *               fArg0;
 603         void *               fArg1;
 604         void *               fArg2;
 605
 606         inline bool
 607         isWorkBlocked( void ) const
 608         {
 609                 return fWorkWaitCount != 0;
 610         }
 611
 612         inline bool
 613         isFreeBlocked( void ) const
 614         {
 615                 return fFreeWaitCount != 0;
 616         }
 617
 618         inline IOPMRequest *
 619         getNextRequest( void ) const
 620         {
 621                 return fRequestNext;
 622         }
 623
 624         inline IOPMRequest *
 625         getRootRequest( void ) const
 626         {
 627                 if (fRequestRoot) {
 628                         return fRequestRoot;
 629                 }
 630 #if NOT_READY
 631                 if (fCompletionAction) {
 632                         return (IOPMRequest *) this;
 633                 }
 634 #endif
 635                 return NULL;
 636         }
 637
 638         inline uint32_t
 639         getType( void ) const
 640         {
 641                 return fRequestType;
 642         }
 643
 644         inline bool
 645         isReplyType( void ) const
 646         {
 647                 return fRequestType > kIOPMRequestTypeReplyStart;
 648         }
 649
 650         inline IOService *
 651         getTarget( void ) const
 652         {
 653                 return fTarget;
 654         }
 655
 656         inline bool
 657         isQuiesceBlocker( void ) const
 658         {
 659                 return fIsQuiesceBlocker;
 660         }
 661
 662         inline bool
 663         isQuiesceType( void ) const
 664         {
 665                 return (kIOPMRequestTypeQuiescePowerTree == fRequestType) &&
 666                        (fCompletionAction != NULL) && (fCompletionTarget != NULL);
 667         }
 668
 669         inline void
 670         installCompletionAction(
 671                 void *               target,
 672                 IOPMCompletionAction action,
 673                 void *               param )
 674         {
 675                 fCompletionTarget = target;
 676                 fCompletionAction = action;
 677                 fCompletionParam  = param;
 678         }
 679
 680         static IOPMRequest * create( void );
 681         bool   init( IOService * owner, IOOptionBits type );
 682         void   reset( void );
 683         bool   attachNextRequest( IOPMRequest * next );
 684         bool   detachNextRequest( void );
 685         bool   attachRootRequest( IOPMRequest * root );
 686         bool   detachRootRequest( void );
 687 };
 688
 689 //******************************************************************************
 690 // IOPMRequestQueue
 691 //******************************************************************************
 692
 693 class IOPMRequestQueue : public IOEventSource
 694 {
 695         OSDeclareDefaultStructors( IOPMRequestQueue );
 696
 697 public:
 698         typedef bool (*Action)( IOService *, IOPMRequest *, IOPMRequestQueue * );
 699
 700 protected:
 701         queue_head_t    fQueue;
 702         IOLock *        fLock;
 703
 704         enum { kMaxDequeueCount = 256 };
 705
 706         virtual bool checkForWork( void ) APPLE_KEXT_OVERRIDE;
 707         virtual void free( void ) APPLE_KEXT_OVERRIDE;
 708         virtual bool init( IOService * inOwner, Action inAction );
 709
 710 public:
 711         static  IOPMRequestQueue * create( IOService * inOwner, Action inAction );
 712         void    queuePMRequest( IOPMRequest * request );
 713         void    queuePMRequestChain( IOPMRequest ** requests, IOItemCount count );
 714 };
 715
 716 //******************************************************************************
 717 // IOPMWorkQueue
 718 //******************************************************************************
 719
 720 #define WORK_QUEUE_STATS    1
 721
 722 class IOPMWorkQueue : public IOEventSource
 723 {
 724         OSDeclareDefaultStructors( IOPMWorkQueue );
 725
 726 public:
 727         typedef bool (*Action)( IOService *, IOPMRequest *, IOPMWorkQueue * );
 728
 729 #if WORK_QUEUE_STATS
 730         uint64_t            fStatCheckForWork;
 731         uint64_t            fStatScanEntries;
 732         uint64_t            fStatQueueEmpty;
 733         uint64_t            fStatNoWorkDone;
 734 #endif
 735
 736 protected:
 737         queue_head_t        fWorkQueue;
 738         Action              fInvokeAction;
 739         Action              fRetireAction;
 740         uint32_t            fQueueLength;
 741         uint32_t            fConsumerCount;
 742         volatile uint32_t   fProducerCount;
 743         IOPMRequest *       fQuiesceRequest;
 744         AbsoluteTime        fQuiesceStartTime;
 745         AbsoluteTime        fQuiesceFinishTime;
 746
 747         virtual bool checkForWork( void ) APPLE_KEXT_OVERRIDE;
 748         virtual bool init( IOService * inOwner, Action invoke, Action retire );
 749         bool    checkRequestQueue( queue_head_t * queue, bool * empty );
 750
 751 public:
 752         static  IOPMWorkQueue * create( IOService * inOwner, Action invoke, Action retire );
 753         bool    queuePMRequest( IOPMRequest * request, IOServicePM * pwrMgt );
 754         void    signalWorkAvailable( void );
 755         void    incrementProducerCount( void );
 756         void    attachQuiesceRequest( IOPMRequest * quiesceRequest );
 757         void    finishQuiesceRequest( IOPMRequest * quiesceRequest );
 758 };
 759
 760 //******************************************************************************
 761 // IOPMCompletionQueue
 762 //******************************************************************************
 763
 764 class IOPMCompletionQueue : public IOEventSource
 765 {
 766         OSDeclareDefaultStructors( IOPMCompletionQueue );
 767
 768 public:
 769         typedef bool (*Action)( IOService *, IOPMRequest *, IOPMCompletionQueue * );
 770
 771 protected:
 772         queue_head_t    fQueue;
 773
 774         virtual bool checkForWork( void ) APPLE_KEXT_OVERRIDE;
 775         virtual bool init( IOService * inOwner, Action inAction );
 776
 777 public:
 778         static  IOPMCompletionQueue * create( IOService * inOwner, Action inAction );
 779         bool    queuePMRequest( IOPMRequest * request );
 780 };
 781
 782 #endif /* !_IOKIT_IOSERVICEPMPRIVATE_H */