X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/1c79356b52d46aa6b508fb032f5ae709b1f2897b..6601e61aa18bf4f09af135ff61fc7f4771d23b06:/iokit/IOKit/IOServicePM.h?ds=sidebyside diff --git a/iokit/IOKit/IOServicePM.h b/iokit/IOKit/IOServicePM.h index 7f958c7c9..55e34fc96 100644 --- 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 @@ -61,110 +61,173 @@ class IOPMpriv : public OSObject 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; - /*! @field interestedDrivers list of interested drivers */ + /*! @var interestedDrivers + List of interested drivers. + */ IOPMinformeeList * interestedDrivers; - /*! @field children list of power domain children */ + /*! @var children + List of power domain children. + */ IOPMinformeeList * children; - /*! @field changeList list of pending power state changes */ + /*! @var changeList + List of pending power state changes. + */ 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; - /*! @field ackTimer */ + /*! @var ackTimer */ thread_call_t ackTimer; - /*! @field settleTimer */ + /*! @var 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; - /*! @field settle_time settle timer after changing power state */ + /*! @var settle_time + Settle timer after changing power state. + */ 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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @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; - /*! @field clampOn domain is clamped on till first child registers */ + /*! @var clampOn + Domain is clamped on till first child registers. + */ 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; - /*! @field activityLock used to protect activity flag */ + /*! @var activityLock + Used to protect activity flag. + */ IOLock * activityLock; - /*! @field timerEventSrc an idle timer */ + /*! @var timerEventSrc + An idle timer. + */ IOTimerEventSource * timerEventSrc; - /*! @field idle_timer_period its period in seconds */ + /*! @var idle_timer_period + Timer's period in seconds. + */ unsigned long idle_timer_period; - /*! @field clampTimerEventSrc timer for clamping power on */ + /*! @var clampTimerEventSrc + Timer for clamping power on. + */ 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; - /*! @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; - /*! @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; - /*! @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. @@ -191,7 +254,7 @@ a subclassed object asks for lower power for some reason via changePowerStateToP 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. @@ -199,20 +262,19 @@ except while a power change is in progress. 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; - /*! @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 -Serialize private instance variables for debug output (IORegistryDumper). + Serialize private instance variables for debug output (IORegistryDumper). */ 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 @@ -233,63 +295,117 @@ class IOPMprot : public OSObject //management public: - /*! @field ourName from getName(), used in logging */ + /*! @var ourName + From getName(), used in logging. + */ const char * ourName; - /*! @field thePlatform from getPlatform, used in logging and registering */ + /*! @var thePlatform + From getPlatform, used in logging and registering. + */ 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 - /*! @field thePowerStates the array */ + /*! @var thePowerStates + The array. + */ IOPMPowerState thePowerStates[IOPMMaxPowerStates]; - /*! @field theControllingDriver points to the controlling driver */ + /*! @var theControllingDriver + Points to the controlling driver. + */ IOService * theControllingDriver; - /*! @field aggressiveness current value of power management aggressiveness */ + /*! @var aggressiveness + Current value of power management 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]; - /*! @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]; - /*! @field myCurrentState the ordinal of our current power state */ + /*! @var myCurrentState + The ordinal of our current power state. + */ 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; - /*! @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; - /*! @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; - /*! @field PMworkloop points to the single power management workloop */ + /*! @var PMworkloop + Points to the single power management workloop. + */ 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; - /*! @field PMcommandGate used to serialize timer expirations and incoming acknowledgements */ + /*! @var PMcommandGate + Used to serialize timer expirations and incoming acknowledgements. + */ 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; - /*! @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; - /*! @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; - /*! @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; + /*! @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). */