iokit/IOKit/IOServicePM.h

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