xnu-792.24.17.tar.gz

[apple/xnu.git] / iokit / IOKit / IOServicePM.h

diff --git a/iokit/IOKit/IOServicePM.h b/iokit/IOKit/IOServicePM.h
index 7f958c7c92e7916a3d5b8c94a4c4673eb3f2f37a..55e34fc967770fad8c02cdcc10a3da8152622061 100644 (file)
--- a/iokit/IOKit/IOServicePM.h
+++ b/iokit/IOKit/IOServicePM.h
@@ -50,7 +50,7 @@ notification from an interested driver or the controlling driver its ack timer i
 
 
 /*!
 
 
 /*!

-@class IOPMpriv : public OSObject
+@class IOPMpriv

 @abstract Private power management private instance variables for IOService objects.
 */
 class IOPMpriv : public OSObject
 @abstract Private power management private instance variables for IOService objects.
 */
 class IOPMpriv : public OSObject


@@ -61,110 +61,173 @@ class IOPMpriv : public OSObject
 
     public:
 
 
     public:
 

-/*! @field we_are_root                 TRUE if this device is the root power domain */
+/*! @var we_are_root 
+    TRUE if this device is the root power domain.
+*/

     bool                       we_are_root;
     
     bool                       we_are_root;
     

-    /*! @field interestedDrivers        list of interested drivers */
+    /*! @var interestedDrivers 
+        List of interested drivers.
+    */

     IOPMinformeeList * interestedDrivers;
     
     IOPMinformeeList * interestedDrivers;
     

-    /*! @field children                 list of power domain children */
+    /*! @var children
+        List of power domain children.
+    */

     IOPMinformeeList * children;
     
     IOPMinformeeList * children;
     

-    /*! @field changeList              list of pending power state changes */
+    /*! @var changeList
+        List of pending power state changes.
+    */

     IOPMchangeNoteList *       changeList;
     
     IOPMchangeNoteList *       changeList;
     

-    /*! @field driver_timer            timeout on waiting for controlling driver to acknowledgeSetPowerState */
+    /*! @var driver_timer
+        Timeout on waiting for controlling driver to acknowledgeSetPowerState.
+    */

     IOReturn                   driver_timer;
     
     IOReturn                   driver_timer;
     

-    /*! @field ackTimer                                                                        */
+    /*! @var ackTimer                                                                  */

     thread_call_t              ackTimer;
 
     thread_call_t              ackTimer;
 

-    /*! @field settleTimer                                                             */
+    /*! @var settleTimer                                                               */

     thread_call_t              settleTimer;
 
     thread_call_t              settleTimer;
 

-    /*! @field machine_state           state number of state machine processing current change note */
+    /*! @var machine_state
+        State number of state machine processing current change note.
+    */

     unsigned long              machine_state;
     
     unsigned long              machine_state;
     

-    /*! @field settle_time             settle timer after changing power state */
+    /*! @var settle_time
+        Settle timer after changing power state.
+    */

     unsigned long              settle_time;
     
     unsigned long              settle_time;
     

-    /*! @field head_note               ordinal of change note currently being processed */
+    /*! @var head_note
+        Ordinal of change note currently being processed.
+    */

     long                       head_note;
     
     long                       head_note;
     

-    /*! @field head_note_flags copy of flags field in change note currently being processed*/
+    /*! @var head_note_flags
+        Copy of flags field in change note currently being processed.
+    */

     unsigned long              head_note_flags;
 
     unsigned long              head_note_flags;
 

-    /*! @field head_note_state copy of newStateNumberfield in change note currently being  processed */
+    /*! @var head_note_state
+        Copy of newStateNumberfield in change note currently being  processed.
+    */

     unsigned long              head_note_state;
 
     unsigned long              head_note_state;
 

-    /*! @field head_note_outputFlags    outputPowerCharacter field from change note currently being processed */
+    /*! @var head_note_outputFlags
+    OutputPowerCharacter field from change note currently being processed.
+    */

     unsigned long              head_note_outputFlags;
 
     unsigned long              head_note_outputFlags;
 

-    /*! @field head_note_domainState           power domain flags from parent... (only on parent change) */
+    /*! @var head_note_domainState
+    Power domain flags from parent... (only on parent change).
+    */

     unsigned long              head_note_domainState;
 
     unsigned long              head_note_domainState;
 

-    /*! @field head_note_parent                pointer to initiating parent... (only on parent change) */
+    /*! @var head_note_parent
+        Pointer to initiating parent... (only on parent change).
+    */

     IOPowerConnection *        head_note_parent;
     
     IOPowerConnection *        head_note_parent;
     

-    /*! @field head_note_capabilityFlags       copy of capabilityFlags field in change note currently being processed */
+    /*! @var head_note_capabilityFlags
+        Copy of capabilityFlags field in change note currently being processed.
+    */

     unsigned long              head_note_capabilityFlags;
 
     unsigned long              head_note_capabilityFlags;
 

-    /*! @field head_note_pendingAcks   number of acks we are waiting for during notification */
+    /*! @var head_note_pendingAcks
+        Number of acks we are waiting for during notification.
+    */

     unsigned long              head_note_pendingAcks;
 
     unsigned long              head_note_pendingAcks;
 

-    /*! @field our_lock                        used to control access to head_note_pendingAcks and driver_timer */
+    /*! @var our_lock
+        Used to control access to head_note_pendingAcks and driver_timer.
+    */

     IOLock     *               our_lock;
 
     IOLock     *               our_lock;
 

-    /*! @field flags_lock              used to control access to response flags array */
+    /*! @var flags_lock
+        Used to control access to response flags array.
+    */

     IOLock     *               flags_lock;
 
     IOLock     *               flags_lock;
 

-    /*! @field initial_change                  true forces first state to be broadcast even if it isn't a change */
+    /*! @var queue_lock
+        Used to control access to change note queue.
+    */
+    IOLock     *               queue_lock;
+
+    /*! @var initial_change
+        True forces first state to be broadcast even if it isn't a change.
+    */

     bool                       initial_change;
 
     bool                       initial_change;
 

-    /*! @field need_to_become_usable   someone called makeUsable before we had a controlling driver */
+    /*! @var need_to_become_usable
+        Someone called makeUsable before we had a controlling driver.
+    */

     bool                       need_to_become_usable;
 
     bool                       need_to_become_usable;
 

-    /*! @field device_overrides                state changes are made based only on subclass's desire */
+    /*! @var device_overrides
+        State changes are made based only on subclass's desire.
+    */

     bool                       device_overrides;
 
     bool                       device_overrides;
 

-    /*! @field clampOn         domain is clamped on till first child registers */
+    /*! @var clampOn
+        Domain is clamped on till first child registers.
+    */

     bool                       clampOn;
 
     bool                       clampOn;
 

-    /*! @field owner                   points to object which made this struct.  Used for debug output only */
+    /*! @var owner
+        Points to object which made this struct.  Used for debug output only.
+    */

     IOService *                owner;
 
     IOService *                owner;
 

-    /*! @field activityLock                    used to protect activity flag */
+    /*! @var activityLock
+        Used to protect activity flag.
+    */

     IOLock *           activityLock;
 
     IOLock *           activityLock;
 

-    /*! @field timerEventSrc           an idle timer */
+    /*! @var timerEventSrc
+        An idle timer.
+    */

     IOTimerEventSource *       timerEventSrc;
 
     IOTimerEventSource *       timerEventSrc;
 

-    /*! @field idle_timer_period               its period in seconds */
+    /*! @var idle_timer_period
+        Timer's period in seconds.
+    */

     unsigned long              idle_timer_period;
    
     unsigned long              idle_timer_period;
    

-    /*! @field clampTimerEventSrc    timer for clamping power on */
+    /*! @var clampTimerEventSrc
+        Timer for clamping power on.
+    */

     IOTimerEventSource *        clampTimerEventSrc;
 
     IOTimerEventSource *        clampTimerEventSrc;
 

-    /*! @field device_active                   true: there has been device activity since last idle timer expiration  */
+    /*! @var device_active
+        True: there has been device activity since last idle timer expiration.
+    */

     bool                       device_active;
 
     bool                       device_active;
 

-    /*! @field driverDesire
-This is the power state desired by our controlling driver.  It is initialized to myCurrentState and is changed
-when the controlling driver calls changePowerStateTo.   A change in driverDesire may cause a change in ourDesiredPowerState.
+    /*! @var device_active_timestamp
+        Time in ticks of last activity.
+    */
+    AbsoluteTime                device_active_timestamp;
+
+    /*! @var driverDesire
+    This is the power state desired by our controlling driver.  It is initialized to myCurrentState and is changed
+    when the controlling driver calls changePowerStateTo.   A change in driverDesire may cause a change in ourDesiredPowerState.

 */
     unsigned long              driverDesire;
 
 
 
 */
     unsigned long              driverDesire;
 
 
 

-    /*! @field deviceDesire
-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.
+    /*! @var deviceDesire
+    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.

 */
     unsigned long              deviceDesire;
 
 
 
 */
     unsigned long              deviceDesire;
 
 
 

-    /*! @field ourDesiredPowerState
+    /*! @var ourDesiredPowerState

 This is the power state we desire currently.  If equal to myCurrentState, we're happy.
 Otherwise, we're waiting for the parent to raise the power domain to at least this level.
     
 This is the power state we desire currently.  If equal to myCurrentState, we're happy.
 Otherwise, we're waiting for the parent to raise the power domain to at least this level.
     


@@ -191,7 +254,7 @@ a subclassed object asks for lower power for some reason via changePowerStateToP
     unsigned long              ourDesiredPowerState;
 
 
     unsigned long              ourDesiredPowerState;
 
 

-    /*! @field previousRequest
+    /*! @var previousRequest

 This is a reminder of what our parent thinks our need is.  Whenever it changes,
 we call requestDomainState in the parent to keep it current.  It is usually equal to ourDesiredPowerState
 except while a power change is in progress.
 This is a reminder of what our parent thinks our need is.  Whenever it changes,
 we call requestDomainState in the parent to keep it current.  It is usually equal to ourDesiredPowerState
 except while a power change is in progress.


@@ -199,20 +262,19 @@ except while a power change is in progress.
     unsigned long              previousRequest;
 
 
     unsigned long              previousRequest;
 
 

-    /*! @field askingFor
-Used by activityTickle so it doesn't try to raise the device to a lower state than
-what it may have previously requested.
+    /*! @var askingFor
+        Not used.

 */
     unsigned long              askingFor;               
 
 
 */
     unsigned long              askingFor;               
 
 

-    /*! @field imminentState
-Usually the same as myCurrentState, except right after calling powerStateWillChangeTo.
+    /*! @var imminentState
+        Usually the same as myCurrentState, except right after calling powerStateWillChangeTo.

 */
     unsigned long              imminentState;
 
     /*! @function serialize
 */
     unsigned long              imminentState;
 
     /*! @function serialize

-Serialize private instance variables for debug output (IORegistryDumper).
+        Serialize private instance variables for debug output (IORegistryDumper).

 */
     virtual bool serialize(OSSerialize *s) const;
 
 */
     virtual bool serialize(OSSerialize *s) const;
 


@@ -222,7 +284,7 @@ Serialize private instance variables for debug output (IORegistryDumper).
 
 
 /*!
 
 
 /*!

-@class IOPMprot : public OSObject
+@class IOPMprott

 @abstract Protected power management instance variables for IOService objects.
 */
 class IOPMprot : public OSObject //management
 @abstract Protected power management instance variables for IOService objects.
 */
 class IOPMprot : public OSObject //management


@@ -233,63 +295,117 @@ class IOPMprot : public OSObject //management
 
     public:
 
 
     public:
 

-        /*! @field ourName                     from getName(), used in logging */
+        /*! @var ourName
+            From getName(), used in logging.
+        */

     const char *               ourName;
 
     const char *               ourName;
 

-    /*! @field thePlatform                     from getPlatform, used in logging and registering */
+    /*! @var thePlatform
+        From getPlatform, used in logging and registering.
+    */

     IOPlatformExpert *         thePlatform;
 
     IOPlatformExpert *         thePlatform;
 

-    /*! @field theNumberOfPowerStates  the number of states in the array */
+    /*! @var theNumberOfPowerStates
+        The number of states in the array.
+    */

     unsigned long              theNumberOfPowerStates;                 // the number of states in the array
 
     unsigned long              theNumberOfPowerStates;                 // the number of states in the array
 

-    /*! @field thePowerStates          the array */
+    /*! @var thePowerStates
+        The array.
+    */

     IOPMPowerState     thePowerStates[IOPMMaxPowerStates];
 
     IOPMPowerState     thePowerStates[IOPMMaxPowerStates];
 

-    /*! @field theControllingDriver            points to the controlling driver */
+    /*! @var theControllingDriver
+        Points to the controlling driver.
+    */

     IOService *                theControllingDriver;
 
     IOService *                theControllingDriver;
 

-    /*! @field aggressiveness          current value of power management aggressiveness */
+    /*! @var aggressiveness
+        Current value of power management aggressiveness.
+    */

     unsigned long              aggressiveness;
 
     unsigned long              aggressiveness;
 

-    /*! @field current_aggressiveness_values    array of aggressiveness values */
+    /*! @var current_aggressiveness_values
+        Array of aggressiveness values.
+    */

     unsigned long               current_aggressiveness_values [kMaxType+1];
 
     unsigned long               current_aggressiveness_values [kMaxType+1];
 

-    /*! @field current_aggressiveness_validity    true for values that are currently valid */
+    /*! @var current_aggressiveness_validity
+        True for values that are currently valid.
+    */

     bool                      current_aggressiveness_valid [kMaxType+1];
 
     bool                      current_aggressiveness_valid [kMaxType+1];
 

-    /*! @field myCurrentState          the ordinal of our current power state */
+    /*! @var myCurrentState
+        The ordinal of our current power state.
+    */

     unsigned long              myCurrentState;
 
     unsigned long              myCurrentState;
 

-    /*! @field parentsKnowState        true if all our parents know the state of their power domain */
+    /*! @var parentsKnowState
+        True if all our parents know the state of their power domain.
+    */

     bool               parentsKnowState;
 
     bool               parentsKnowState;
 

-    /*! @field parentsCurrentPowerFlags        logical OR of power flags for the current state of each power domainparent */
+    /*! @var parentsCurrentPowerFlags
+        Logical OR of power flags for the current state of each power domainparent.
+    */

     IOPMPowerFlags     parentsCurrentPowerFlags;
 
     IOPMPowerFlags     parentsCurrentPowerFlags;
 

-    /*! @field maxCapability                   ordinal of highest state we can achieve in current power domain state */
+    /*! @var maxCapability
+        Ordinal of highest state we can achieve in current power domain state.
+    */

     unsigned long              maxCapability;
 
     unsigned long              maxCapability;
 

-    /*! @field PMworkloop                      points to the single power management workloop */
+    /*! @var PMworkloop
+        Points to the single power management workloop.
+    */

     IOWorkLoop *               PMworkloop;
 
     IOWorkLoop *               PMworkloop;
 

-    /*! @field commandQueue            used to serialize idle-power-down and busy-power-up */
+    /*! @var commandQueue
+        Used to serialize idle-power-down and busy-power-up.
+    */

     IOCommandQueue *   commandQueue;
 
     IOCommandQueue *   commandQueue;
 

-    /*! @field PMcommandGate           used to serialize timer expirations and incoming acknowledgements */
+    /*! @var PMcommandGate
+        Used to serialize timer expirations and incoming acknowledgements.
+    */

     IOCommandGate *    PMcommandGate;
 
     IOCommandGate *    PMcommandGate;
 

-    /*! @field myCharacterFlags                logical OR of all output power character flags in the array */
+    /*! @var myCharacterFlags
+        Logical OR of all output power character flags in the array.
+    */

     IOPMPowerFlags             myCharacterFlags;
 
     IOPMPowerFlags             myCharacterFlags;
 

-    /*! @field serialNumber            used to uniquely identify power management notification to apps and clients */
+    /*! @var serialNumber
+        Used to uniquely identify power management notification to apps and clients.
+    */

     UInt16   serialNumber;
 
     UInt16   serialNumber;
 

-    /*! @field responseFlags           points to an OSArray which manages responses from notified apps and clients */
+    /*! @var responseFlags
+        Points to an OSArray which manages responses from notified apps and clients.
+    */

     OSArray* responseFlags;
     
     OSArray* responseFlags;
     

-    /*! @field doNotPowerDown          keeps track of any negative responses from notified apps and clients */
+    /*! @var doNotPowerDown
+        Keeps track of any negative responses from notified apps and clients.
+    */

     bool       doNotPowerDown;
     
     bool       doNotPowerDown;
     

+    /*! @var childLock
+        Used to serialize scanning the children.
+    */
+    IOLock     *               childLock;
+
+    /*! @var parentLock
+        Used to serialize scanning the parents.
+    */
+    IOLock     *               parentLock;
+
+    /*! @var outofbandparameter
+        Used to communicate desired function to tellClientsWithResponse().
+        This is used because it avoids changing the signatures of the affected virtual methods. 
+    */
+    int                                outofbandparameter;
+

     /*! @function serialize
 Serialize protected instance variables for debug output (IORegistryDumper).
 */
     /*! @function serialize
 Serialize protected instance variables for debug output (IORegistryDumper).
 */