iokit/Kernel/IOServicePM.cpp

288  There are two different kinds of power state changes.
290       to change power state, or its controlling driver has suggested it, or
293     * The second kind of power state change is initiated by the power domain
300     * It's possible to have more than one power state change pending at one
304         power state. This causes interested parties to be notified, but they
310         time, the parent decides to lower or raise the power state of the entire
320     -> We call the controlling driver, instructing it to change to the new state
327  state, we suggest to the parent that it lower the power domain state.
330 How a change to a lower power domain state initiated by the parent is handled:
331     -> First, we figure out what power state we will be in when the new domain
332         state is reached.
334         state.
336         that state and we wait for power to settle.
341         state has changed, and when they have all acknowledged, we're done.
344 How a change to a higher power domain state initiated by the parent is handled:
345     -> We figure out what power state we will be in when the new domain state is
347     -> If it is different from our current state we acknowledge the parent.
350     -> Then it  notifies everyone that the new state has been reached.
352         assume the new state, and wait for power to settle.
356  In either of the two power domain state cases above, it is possible that we
357  will not be changing state even though the domain is.
359     * A change to a lower domain state may not affect us because we are already
360         in a low enough state,
361     * We will not take advantage of a change to a higher domain state, because
365         state, we merely acknowledge the parent, via return code, and wait.
370  Power state changes are processed in a state machine, and since there are four
371  varieties of power state changes, there are four major paths through the state
376  state, but we are not changing the device state. The change starts when the
391         -> If they all acknowledge via return code, we can go on to state
395             -> We move on to state "msSetPowerState" when all the
399  power state of the hardware.
400     -> If it returns saying it has done so, we go on to state
405  In "msWaitForPowerSettle", we look in the power state array to see if
406  there is any settle time required when changing from our current state to the
407  new state.
410  In "msNotifyInterestedDriversDidChange" state, we notify all our
412  changing power state.
809     // no more power state changes
1044         // initially change into the state we are already in
1094 // power domain state, what state it would be in, and then tell it
1095 // to assume that state.
1208 		// Make a copy of the supplied power state array.
1278                 // The minimum power state that the device is usable
1332 			// initially change into the state we are already in
1350 // power state.  If we don't have a power-controlling driver yet, we will
1352 // out what the current power state of the device is.
1645 // We continue to process the power state change.
1684 			 /* power state  */	fDesiredPowerState,
1756 			 /* power state  */	fCurrentPowerState,
1767 // Called by the power-hierarchy parent notifying of a new power state
1846                  /* power state  */	newPowerState,
1861 	// Parent is expecting an ACK from us. If we did not embark on a state
1886 // Called by the power-hierarchy parent after the power state of the power domain
1944             // re-compute desired state in case advisory tickle was enabled
1954                  /* power state  */	newPowerState,
1960 	// Parent is expecting an ACK from us. If we did not embark on a state
2118     // at its current or impending power state.
2125 			// Use the lower power state when dropping power.
2134 			// re-evaluate the parent's power state.
2144 				PM_LOG1("%s: power drop cancelled in state %u by %s\n",
2149 				// Beyond cancellation point, report the impending state.
2160 			// for the next power state, then using the power supplied by
2169     // Map child's requested power flags to one of our power state.
2206 	// adjust power state. Submit a request if one wasn't pending,
2228 // will thendetermine the power domain state.
2230 // We enter the highest state until addPowerChild is called.
2247 // highest power state.
2271 // Called by our power-controlling driver to change power state. The new desired
2272 // power state is computed and compared against the current power state. If those
2273 // power states differ, then a power state change is initiated.
2285 // Called by our driver subclass to change power state. The new desired power
2286 // state is computed and compared against the current power state. If those
2287 // power states differ, then a power state change is initiated.
2299 // Called by our driver subclass to change power state. The new desired power
2300 // state is computed and compared against the current power state. If those
2301 // power states differ, then a power state change is initiated.
2348     uint32_t              state )
2362     request->fArg0 = (void *) state;
2373 	if (gIOPMWorkLoop->inGate() && (state < fNumberOfPowerStates))
2375 		fTempClampPowerState = max(fTempClampPowerState, state);
2391     uint32_t         state  = (uint32_t)(uintptr_t) request->fArg0;
2401 	if (fNumberOfPowerStates && (state >= fNumberOfPowerStates))
2402 		state = fNumberOfPowerStates - 1;
2411     if ((state == 0) &&
2417 		updatePowerClient(client, state);
2550 	// Desired power state is always 0 without a controlling driver.
2559     // Examine the children's desired power state.
2587     // Iterate through all power clients to determine the min power state.
2662     // Invalidate cached tickle power state when desires change, and not
2664     // power state change to minimize races.  We want to err on the side
2666     // the device is in a low power state.
2788 // flag to be set, and the device state checked.  If the device has been
2814 		// Record the last tickle power state.
2826 				request->fArg0 = (void *) stateNumber;  // power state
2851 				request->fArg0 = (void *) stateNumber;  // power state
2862 	// higher powered state, true otherwise.
2897             // system wakes up to doze state, while the device is unable to
2898             // raise its power state to satisfy the tickle.
2985 // next lowest power state.
3081 // activity, switch to the next lower power state and restart the timer.
3103 		// No device activity - drop power state by one level.
3104 		// Decrement the cached tickle power state when possible.
3114 			request->fArg0 = (void *) 0;		// power state (irrelevant)
3138 			request->fArg0 = (void *) 0;		// power state (irrelevant)
3301 // All power state changes starts here.
3404     // Block state machine and wait for callout completion.
3728 			panic("IOService::pmDriverCallout bad machine state %x",
4003     // Block state machine and wait for callout completion.
4122         // could our driver switch to the new state?
4242 	// fMaxPowerState is our maximum possible power state based on the current
4243 	// power state of our parents.  If we are trying to raise power beyond the
4254 	// Redundant power changes skips to the end of the state machine.
4275         // Ask for persmission to drop power state
4283         // new power state. However a parent may have already committed to
4285         // This results in "oscillations" before the state machines converge
4286         // to a steady state.
4290         // that the child will be unable to sustain the higher power state,
4365     // Fetch the input power flags for the requested power state.
4427         // Ask for permission to drop power state
4469 // system capability change when raising power state.
4483 // All applications and kernel clients have acknowledged our power state change.
4513 // Instruct our controlling driver to program the hardware for the power state
4530 // Our controlling driver has completed the power state change we initiated.
4581 // Done with this self-induced power state change.
4656             // We do not need to change power state, but notify
4700 // All applications and kernel clients have acknowledged our power state change.
4712 // Instruct our controlling driver to program the hardware for the power state
4729 // Our controlling driver has completed the power state change initiated by our
4830         // Force the next tickle to raise power state
4861 // there is a new power state.
4944 // state of the hardware, we decrement its timer word, and if it becomes
4948 // machine state, false otherwise.
5002 						// Unblock state machine and pretend driver has acked.
5091             PM_LOG1("%s: unexpected ack timer tick (state = %d)\n",
5146 	// done will be true if the timer tick unblocks the machine state,
5205 // power state.
5208 // the destination state number.
5254 // the destination state number.
5874 // the aborted destination state number.
5888 // the aborted destination state number.
6185 // Our power state is about to lower, and we have notified applications
6223 // Our power state is about to lower, and we have notified applications
6268 // called when clamp timer expires...set power state to 0.
6278 // Set to highest available power state for a minimum of duration milliseconds
6304 // Finds the highest power state in the array whose input power
6331 // Finds the highest power state in the array whose input power
6358 // Finds the highest power state in the array whose input power
6602 	PM_LOG1("[- %02x] %p [%p %s] state %d, busy %d\n",
6640 // Check if machine state transition is blocked.
6692 			PM_LOG1("[B %02x] %p [%p %s] state %d, reason %d\n",
6718 		PM_LOG1("[W %02x] %p [%p %s] state %d\n",
6796 					// no, tell clients we're back in the old state
6991 				panic("servicePMWorkQueue: unknown machine state %x",
7101 	PM_LOG1("[A %02x] %p [%p %s] state %d\n",
7203                 PM_LOG2("%s: cancel from machine state %d\n",
7711             break;  // work started, blocked on PM state machine