iokit/IOKit/IOServicePM.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30
  31 extern "C" {
  32 #include <kern/thread_call.h>
  33 }
  34
  35 #include <libkern/c++/OSObject.h>
  36 #include <IOKit/IOLocks.h>
  37 class IOPMinformee;
  38 class IOPMinformeeList;
  39 class IOPMchangeNoteList;
  40 class IOPMpmChild;
  41 class IOWorkLoop;
  42 class IOCommandQueue;
  43 class IOCommandGate;
  44 class IOTimerEventSource;
  45 class IOPlatformExpert;
  46
  47 #include <IOKit/pwr_mgt/IOPM.h>
  48
  49
  50 /*!
  51 @defined ACK_TIMER_PERIOD
  52 @discussion When an IOService is waiting for acknowledgement to a power state change
  53 notification from an interested driver or the controlling driver its ack timer is ticking every tenth of a second.
  54 (100000000 nanoseconds are one tenth of a second).
  55 */
  56  #define ACK_TIMER_PERIOD 100000000
  57
  58
  59
  60 /*!
  61 @class IOPMpriv
  62 @abstract Private power management private instance variables for IOService objects.
  63 */
  64 class IOPMpriv : public OSObject
  65 {
  66     friend class IOService;
  67
  68     OSDeclareDefaultStructors(IOPMpriv)
  69
  70     public:
  71
  72 /*! @var we_are_root
  73     TRUE if this device is the root power domain.
  74 */
  75     bool                        we_are_root;
  76
  77     /*! @var interestedDrivers
  78         List of interested drivers.
  79     */
  80     IOPMinformeeList *  interestedDrivers;
  81
  82     /*! @var children
  83         List of power domain children.
  84     */
  85     IOPMinformeeList *  children;
  86
  87     /*! @var changeList
  88         List of pending power state changes.
  89     */
  90     IOPMchangeNoteList *        changeList;
  91
  92     /*! @var driver_timer
  93         Timeout on waiting for controlling driver to acknowledgeSetPowerState.
  94     */
  95     IOReturn                    driver_timer;
  96
  97     /*! @var ackTimer                                                                   */
  98     thread_call_t               ackTimer;
  99
 100     /*! @var settleTimer                                                                */
 101     thread_call_t               settleTimer;
 102
 103     /*! @var machine_state
 104         State number of state machine processing current change note.
 105     */
 106     unsigned long               machine_state;
 107
 108     /*! @var settle_time
 109         Settle timer after changing power state.
 110     */
 111     unsigned long               settle_time;
 112
 113     /*! @var head_note
 114         Ordinal of change note currently being processed.
 115     */
 116     long                        head_note;
 117
 118     /*! @var head_note_flags
 119         Copy of flags field in change note currently being processed.
 120     */
 121     unsigned long               head_note_flags;
 122
 123     /*! @var head_note_state
 124         Copy of newStateNumberfield in change note currently being  processed.
 125     */
 126     unsigned long               head_note_state;
 127
 128     /*! @var head_note_outputFlags
 129     OutputPowerCharacter field from change note currently being processed.
 130     */
 131     unsigned long               head_note_outputFlags;
 132
 133     /*! @var head_note_domainState
 134     Power domain flags from parent... (only on parent change).
 135     */
 136     unsigned long               head_note_domainState;
 137
 138     /*! @var head_note_parent
 139         Pointer to initiating parent... (only on parent change).
 140     */
 141     IOPowerConnection *         head_note_parent;
 142
 143     /*! @var head_note_capabilityFlags
 144         Copy of capabilityFlags field in change note currently being processed.
 145     */
 146     unsigned long               head_note_capabilityFlags;
 147
 148     /*! @var head_note_pendingAcks
 149         Number of acks we are waiting for during notification.
 150     */
 151     unsigned long               head_note_pendingAcks;
 152
 153     /*! @var our_lock
 154         Used to control access to head_note_pendingAcks and driver_timer.
 155     */
 156     IOLock      *               our_lock;
 157
 158     /*! @var flags_lock
 159         Used to control access to response flags array.
 160     */
 161     IOLock      *               flags_lock;
 162
 163     /*! @var queue_lock
 164         Used to control access to change note queue.
 165     */
 166     IOLock      *               queue_lock;
 167
 168     /*! @var initial_change
 169         True forces first state to be broadcast even if it isn't a change.
 170     */
 171     bool                        initial_change;
 172
 173     /*! @var need_to_become_usable
 174         Someone called makeUsable before we had a controlling driver.
 175     */
 176     bool                        need_to_become_usable;
 177
 178     /*! @var device_overrides
 179         State changes are made based only on subclass's desire.
 180     */
 181     bool                        device_overrides;
 182
 183     /*! @var clampOn
 184         Domain is clamped on till first child registers.
 185     */
 186     bool                        clampOn;
 187
 188     /*! @var owner
 189         Points to object which made this struct.  Used for debug output only.
 190     */
 191     IOService *                 owner;
 192
 193     /*! @var activityLock
 194         Used to protect activity flag.
 195     */
 196     IOLock *            activityLock;
 197
 198     /*! @var timerEventSrc
 199         An idle timer.
 200     */
 201     IOTimerEventSource *        timerEventSrc;
 202
 203     /*! @var idle_timer_period
 204         Timer's period in seconds.
 205     */
 206     unsigned long               idle_timer_period;
 207
 208     /*! @var clampTimerEventSrc
 209         Timer for clamping power on.
 210     */
 211     IOTimerEventSource *        clampTimerEventSrc;
 212
 213     /*! @var device_active
 214         True: there has been device activity since last idle timer expiration.
 215     */
 216     bool                        device_active;
 217
 218     /*! @var device_active_timestamp
 219         Time in ticks of last activity.
 220     */
 221     AbsoluteTime                device_active_timestamp;
 222
 223     /*! @var driverDesire
 224     This is the power state desired by our controlling driver.  It is initialized to myCurrentState and is changed
 225     when the controlling driver calls changePowerStateTo.   A change in driverDesire may cause a change in ourDesiredPowerState.
 226 */
 227     unsigned long               driverDesire;
 228
 229
 230
 231     /*! @var deviceDesire
 232     This is the power state desired by a subclassed device object.  It is initialized to myCurrentState and is changed when the subclassed object calls changePowerStateToPriv.  A change in deviceDesire may cause a change in ourDesiredPowerState.
 233 */
 234     unsigned long               deviceDesire;
 235
 236
 237
 238     /*! @var ourDesiredPowerState
 239 This is the power state we desire currently.  If equal to myCurrentState, we're happy.
 240 Otherwise, we're waiting for the parent to raise the power domain to at least this level.
 241
 242 If this is a power domain, this is the maximum of all our children's desires, driverDesire, and deviceDesire.
 243 It increases when:
 244 a child asks for more power via requestDomainState,
 245 the controlling driver asks for more power via changePowerStateTo
 246
 247 It decreases when:
 248 we lose a child and the child had the highest power need of all our children,
 249 the child with the highest power need suggests a lower power domain state,
 250 the controlling driver asks for lower power for some reason via changePowerStateTo
 251
 252 If this is not a power domain, ourDesiredPowerState represents the greater of driverDesire and deviceDesire.
 253 It increases when:
 254 the controlling driver asks for more power via changePowerStateTo
 255 some driver calls makeUsable
 256 a subclassed object asks for more power via changePowerStateToPriv
 257
 258 It decreases when:
 259 the controlling driver asks for lower power for some reason via changePowerStateTo
 260 a subclassed object asks for lower power for some reason via changePowerStateToPriv
 261 */
 262     unsigned long               ourDesiredPowerState;
 263
 264
 265     /*! @var previousRequest
 266 This is a reminder of what our parent thinks our need is.  Whenever it changes,
 267 we call requestDomainState in the parent to keep it current.  It is usually equal to ourDesiredPowerState
 268 except while a power change is in progress.
 269 */
 270     unsigned long               previousRequest;
 271
 272
 273     /*! @var askingFor
 274         Not used.
 275 */
 276     unsigned long               askingFor;
 277
 278
 279     /*! @var imminentState
 280         Usually the same as myCurrentState, except right after calling powerStateWillChangeTo.
 281 */
 282     unsigned long               imminentState;
 283
 284     /*! @function serialize
 285         Serialize private instance variables for debug output (IORegistryDumper).
 286 */
 287     virtual bool serialize(OSSerialize *s) const;
 288
 289 };
 290
 291
 292
 293
 294 /*!
 295 @class IOPMprott
 296 @abstract Protected power management instance variables for IOService objects.
 297 */
 298 class IOPMprot : public OSObject //management
 299 {
 300     friend class IOService;
 301
 302     OSDeclareDefaultStructors(IOPMprot)
 303
 304     public:
 305
 306         /*! @var ourName
 307             From getName(), used in logging.
 308         */
 309     const char *                ourName;
 310
 311     /*! @var thePlatform
 312         From getPlatform, used in logging and registering.
 313     */
 314     IOPlatformExpert *  thePlatform;
 315
 316     /*! @var theNumberOfPowerStates
 317         The number of states in the array.
 318     */
 319     unsigned long               theNumberOfPowerStates;                 // the number of states in the array
 320
 321     /*! @var thePowerStates
 322         The array.
 323     */
 324     IOPMPowerState      thePowerStates[IOPMMaxPowerStates];
 325
 326     /*! @var theControllingDriver
 327         Points to the controlling driver.
 328     */
 329     IOService *                 theControllingDriver;
 330
 331     /*! @var aggressiveness
 332         Current value of power management aggressiveness.
 333     */
 334     unsigned long               aggressiveness;
 335
 336     /*! @var current_aggressiveness_values
 337         Array of aggressiveness values.
 338     */
 339     unsigned long               current_aggressiveness_values [kMaxType+1];
 340
 341     /*! @var current_aggressiveness_validity
 342         True for values that are currently valid.
 343     */
 344     bool                       current_aggressiveness_valid [kMaxType+1];
 345
 346     /*! @var myCurrentState
 347         The ordinal of our current power state.
 348     */
 349     unsigned long               myCurrentState;
 350
 351     /*! @var parentsKnowState
 352         True if all our parents know the state of their power domain.
 353     */
 354     bool                parentsKnowState;
 355
 356     /*! @var parentsCurrentPowerFlags
 357         Logical OR of power flags for the current state of each power domainparent.
 358     */
 359     IOPMPowerFlags      parentsCurrentPowerFlags;
 360
 361     /*! @var maxCapability
 362         Ordinal of highest state we can achieve in current power domain state.
 363     */
 364     unsigned long               maxCapability;
 365
 366     /*! @var PMworkloop
 367         Points to the single power management workloop.
 368     */
 369     IOWorkLoop *                PMworkloop;
 370
 371     /*! @var commandQueue
 372         Used to serialize idle-power-down and busy-power-up.
 373     */
 374     IOCommandQueue *    commandQueue;
 375
 376     /*! @var PMcommandGate
 377         Used to serialize timer expirations and incoming acknowledgements.
 378     */
 379     IOCommandGate *     PMcommandGate;
 380
 381     /*! @var myCharacterFlags
 382         Logical OR of all output power character flags in the array.
 383     */
 384     IOPMPowerFlags              myCharacterFlags;
 385
 386     /*! @var serialNumber
 387         Used to uniquely identify power management notification to apps and clients.
 388     */
 389     UInt16   serialNumber;
 390
 391     /*! @var responseFlags
 392         Points to an OSArray which manages responses from notified apps and clients.
 393     */
 394     OSArray* responseFlags;
 395
 396     /*! @var doNotPowerDown
 397         Keeps track of any negative responses from notified apps and clients.
 398     */
 399     bool        doNotPowerDown;
 400
 401     /*! @var childLock
 402         Used to serialize scanning the children.
 403     */
 404     IOLock      *               childLock;
 405
 406     /*! @var parentLock
 407         Used to serialize scanning the parents.
 408     */
 409     IOLock      *               parentLock;
 410
 411     /*! @var outofbandparameter
 412         Used to communicate desired function to tellClientsWithResponse().
 413         This is used because it avoids changing the signatures of the affected virtual methods.
 414     */
 415     int                         outofbandparameter;
 416
 417     /*! @function serialize
 418 Serialize protected instance variables for debug output (IORegistryDumper).
 419 */
 420     virtual bool serialize(OSSerialize *s) const;
 421
 422 };
 423