Power Events

Before you consider how to implement power management in your driver, you need to understand what power events are and how they can affect your device. In OS X, power events are transitions to and from the following states:

• Sleep

• Wake

• Shutdown or restart

All drivers must respond to sleep events. OS X defines different types of sleep, which can occur for different reasons. For example, system sleep occurs when the user chooses Sleep from the Apple menu or closes the lid of a laptop; idle sleep occurs when there has been no device or system activity during the interval the user selects in the Energy Saver preferences. To your driver, however, all sleep events appear identical. The important thing to understand about a sleep event is that your device may be powered off when the system sleeps, so your driver must be prepared to initialize the device when it is awakened.

All drivers must respond to a system wake event by powering on. Wake can occur when the user hits a key on the keyboard, presses the power button, or when the computer receives a network administrator wake-up packet. On wake, drivers should perform the appropriate restoration of device state.

Device drivers do not have to respond to shutdown and restart events. A driver can choose to get notification of an impending shutdown or restart using the technique described in Receiving Shutdown and Restart Notifications but it’s important to understand that no driver can prevent a shutdown event.

Another type of event is a device power-up request, which occurs when some object in the system requires an idle or powered-off device to be in a usable state. A device power-up request notification uses most of the same mechanisms as sleep and wake notifications. Although most drivers do not need to know about device power-up requests, some drivers might need to implement them and even make such requests themselves. For more information about this, see Initiating a Power-State Change

The Power Plane: A Hierarchy of Power Dependencies

OS X tracks all power-managed devices in a tree-like structure, called the power plane, that captures the power dependencies among devices. A device, usually a leaf object in the power plane, generally receives power from its ancestors and may provide power to its children. For example, because a PCI card depends for power on the PCI bus to which it’s attached, the PCI card is considered to be a power child of the PCI bus. Likewise, the PCI bus is considered to be the power parent of the devices attached to it.

The power plane is one of the planes of the I/O Registry. As described in The I/O Registry the I/O Registry is a dynamic database of device and driver objects that expresses the various provider-client relationships among them. To view the power plane in a running system, open the I/O Registry Explorer application (located in /Developer/Applications/Utilities) and choose IOPower from the pop-up menu. You can also enter ioreg -p IOPower at the command line to see a representation of the current power plane. Figure 9-1 shows the power plane in a Power Mac G5 running OS X v10.5.

In Figure 9-1 you can see the root of the power plane, an object called IOPMrootDomain, and objects that represent devices and drivers. You can ignore the many IOPowerConnection objects, which represent power connections, because these objects are of interest only to internal power-management objects and processes.

Devices and Power States

The fundamental entity in power management is the device. From a power-management perspective, a device is a unit of hardware whose power consumption can be measured and controlled independently of system power. A device can also have some state that needs to be saved and restored across changes in power. In power-management terms, “device” is synonymous with the device-driver object that controls it.

A device must have at least two power states associated with it—off and on. A device may also have intermediate states that represent some level of power between full power and no power. These states are described in a power-state array you create in your driver. (You learn how to create this array and provide power-state information in step 3 in Implementing Basic Power Management) The power-management functionality of the I/O Kit uses these states to ensure that all drivers in the power plane receive the power they require. Each power state is defined by the device’s capabilities when in that state:

• A device that is on uses maximum power and has complete functionality.

• A device that is off uses no power and has no functionality.

• A device can be in a reduced-power state in which it is still usable, but at a lower level of performance or functionality.

• A device can be in an intermediate state in which it is not usable, but retains some configuration or state.

The power-management functionality of the I/O Kit associates several attributes with each power state of a device. A device driver must set these attributes to ensure that accurate information about the device’s capabilities and requirements is available.

The power-state attributes provide the following information:

• The capability of the device while in a given state

• The device’s power requirements of its power parent

• The power characteristics the device can provide to its power children

• The version of the power-state structure the device uses to store its power-state information

Deciding How to Implement Power Management in Your Driver

To participate in OS X power management, most in-kernel drivers need only ensure that their devices respond appropriately to system sleep and wake events. Some in-kernel drivers might need to perform other tasks, such as implementing an idle state or taking action at system shutdown, but these drivers are not typical. Reflecting this distinction, OS X power management defines two types of drivers:

• A passive driver implements basic power management to respond to system power events; it does not initiate any power-related actions for its device.

• An active driver implements basic power management to respond to system power events, but it also implements advanced power management to perform tasks such as deciding when the device should become idle, changing the device’s power state, or processing prior to system shutdown.

An example of a passive driver is the AppleSmartBatteryManager driver present in most Macintosh laptop computers. The AppleSmartBatteryManager driver provides battery-status information to the battery-status menu bar item; when the system is about to sleep, the driver simply stops polling the battery for status information. A good example of an active driver is the built-in audio chip driver, because it performs its own idleness determination to allow the audio hardware to power off when it is not in use. If there is no sound coming out of a laptop's or desktop's internal speakers, the audio hardware will drop into a low power mode until it is needed.

As you can imagine, a passive driver is much easier than an active driver to design and implement. Essentially, a passive driver implements one virtual method and makes between three and five calls to participate in power management. The responsibilities of an active driver, on the other hand, begin with those of a passive driver, but increase with each additional task the driver needs to perform.

Some I/O Kit families provide various levels of built-in power-management support to driver subclasses. For example, the Network family (IONetworkingFamily) performs some of the power-management initialization tasks for a subclass driver, leaving the driver to perform other device-specific power-management tasks.

Before you begin designing your driver’s power-management implementation, you should look up your I/O Kit family in I/O Kit Family Reference to find out if the family provides any power-management support or requires subclasses to perform different or additional tasks. Be aware, however, that any I/O Kit family that provides power-management functionality may still require you to implement some parts of it. The following I/O Kit families provide some type of power-management functionality:

• Audio family (described in Audio)

• FireWire family (described in FireWire)

• Network family (described in Network)

• PC card family, which includes Express Card devices (described in PC Card)

• PCI family (described in PCI and AGP)

• SCSI Architecture Model family (described in SCSI Architecture Model)

• USB family (described in USB)

Even if your driver is a subclass of an I/O Kit family that does not provide any power-management support, or if your driver is a direct subclass of IOService, it can still be a passive power-management participant as long as it only responds to system-initiated power events. If, on the other hand, your driver needs to determine when your device is idle or perform pre-shutdown tasks, you must implement advanced power management.

If you decide to develop a passive driver, you should read Implementing Basic Power Management to learn how to participate in power management and respond to sleep and wake events. You do not need to read any other sections in this chapter.

If your driver needs to be an active power manager, you should also read Implementing Basic Power Management Then you should read Implementing Advanced Power Management for guidance on implementing specific tasks.

Implementing Basic Power Management

As defined in Deciding How to Implement Power Management in Your Driver a passive driver only responds to sleep and wake events; it does not initiate any power state–changing activity. Your passive driver must do the following things to handle sleep and wake:

• Get attached into the power plane so you receive power-change notifications and to ensure that your device’s power dependencies are considered when it is told to sleep and wake.

  Power dependencies affect the ordering of sleep and wake notifications. Specifically, your driver is told to sleep before its power parent is told to sleep, and your driver is told to wake after its power parent is told to wake.

• Save hardware state to memory before system sleep and restore state during wake.

  You are responsible for writing code to do this.

• Prevent all hardware accesses while your device is preparing for sleep.

  You can return an error to any I/O request you receive while your device is going to sleep or you can block all incoming threads using a gating mechanism, such as IOCommandGate, on your work loop (see Work Loops to learn more about work loops).

To participate in power management so that you receive notifications of power events, ensure your driver is correctly attached into the power plane, and handle power-state changes, you make a few calls and implement one virtual method. The IOService class provides all the methods described in this section. Follow the steps listed below to implement basic power management in your driver.

1. Initialize power management using PMinit. The () method allocates internal power-management data structures that allow internal processes to track your driver.

   In your driver’s start routine, after the call to your superclass’s start method, make the following call:

   PMinit();

2. Get attached into the power plane using joinPMtree. The (IOService*) method attaches the passed-in driver object into the power plane as a child of its provider.

   In your driver’s start routine, after the call to PMinit and before the call to registerPowerDriver (shown in step 3), call joinPMtree as shown below:

   provider->joinPMtree(this);

3. Provide information about your device’s power states and register your driver with power management.

   1. First, declare an array of two structures to contain information about your device’s off and on states. The first element in the array must contain the structure that describes the off state and the second element of the array must contain the structure that describes the on state. Typically, a driver switches its device to the off state in response to a sleep event and to the on state in response to a wake event, as described in Power Events

      In your driver’s start routine, after the call to joinPMtree, fill in two IOPMPowerState structures, as shown below:

      // Declare an array of two IOPMPowerState structures (kMyNumberOfStates = 2).

      static IOPMPowerState myPowerStates[kMyNumberOfStates];

      // Zero-fill the structures.

      bzero (myPowerStates, sizeof(myPowerStates));

      // Fill in the information about your device's off state:

      myPowerStates[0].version = 1;

      myPowerStates[0].capabilityFlags = kIOPMPowerOff;

      myPowerStates[0].outputPowerCharacter = kIOPMPowerOff;

      myPowerStates[0].inputPowerRequirement = kIOPMPowerOff;

      // Fill in the information about your device's on state:

      myPowerStates[1].version = 1;

      myPowerStates[1].capabilityFlags = kIOPMPowerOn;

      myPowerStates[1].outputPowerCharacter = kIOPMPowerOn;

      myPowerStates[1].inputPowerRequirement = kIOPMPowerOn;

      In some drivers, you might see this step implemented in code similar to the following:

      static IOPMPowerState myPowerStates[kMyNumberOfStates] = {

      {1, kIOPMPowerOff, kIOPMPowerOff, kIOPMPowerOff, 0, 0, 0, 0, 0, 0, 0, 0},

      {1, kIOPMPowerOn, kIOPMPowerOn, kIOPMPowerOn, 0, 0, 0, 0, 0, 0, 0, 0}

      };

   2. Then, still in your driver’s start routine, register your driver with power management using (IOService*,IOPMPowerState*,unsignedlong). The registerPowerDriver method tells power management that the passed-in driver object can transition the device between the power states described in the passed-in array. After you fill in the IOPMPowerState structures, call registerPowerDriver with your power-state array as shown below:

      registerPowerDriver (this, myPowerStates, kMyNumberOfStates);

4. Handle power-state changes using setPowerState. While your driver is running, you perform tasks that handle sleep and wake event notifications in your implementation of the virtual IOService method setPowerState. An example of how to do this is shown below:

   IOReturn MyIOServiceDriver::setPowerState ( unsigned long whichState, IOService * whatDevice )

   // Note that it is safe to ignore the whatDevice parameter.

   {

   if ( 0 == whichState ) {

   // Going to sleep. Perform state-saving tasks here.

   } else {

   // Waking up. Perform device initialization here.

   }

   if ( done )

   return kIOPMAckImplied;

   else

   return (/* a number of microseconds that represents the maximum time required to prepare for the state change */);

   }

   If you return kIOPMAckImplied, you signal that you’ve completed the transition to the new power state. If you do not return kIOPMAckImplied and instead return the maximum amount of time it takes to prepare your device for the power-state change, you must be sure to call acknowledgeSetPowerState when you have finished the power-state transition. If you do not call acknowledgeSetPowerState before the length of time you specify has elapsed, the system continues with its power-state change as if you had returned kIOPMAckImplied in the first place.

5. Unregister from power management when your driver unloads using PMstop. The PMstop method handles all the necessary cleanup, including the removal of your driver from the power plane. Because PMstop may put your hardware into its off state, be sure to complete all hardware accesses before you call it.

   In your driver’s stop routine, after you finish all calls that might access your hardware, call PMstop as shown below:

   PMstop();

Implementing Advanced Power Management

This section delves deeper into the power-management functionality of the I/O Kit. The vast majority of driver developers do not need to understand the information in this section because basic power management (as described in Deciding How to Implement Power Management in Your Driver) is sufficient for most devices. If your device can be passively power managed, read Implementing Basic Power Management instead.

You should read this section if your driver needs to perform advanced power-management tasks, such as determining device idleness, taking action when the system is about to shutdown, or deciding to change the device’s power state. Of course, active drivers share some tasks with passive drivers, namely the initialization and tear-down of power management. Before you read about the tasks in this section, therefore, you should glance at the steps in Implementing Basic Power Management to learn how to initialize and terminate power management in your driver. Even if your driver must perform advanced power-management tasks, it still needs to call PMinit, joinPMtree, registerPowerDriver, and PMstop and implement setPowerState, as shown in Implementing Basic Power Management

This section covers several tasks an active driver might need to perform. Although few active drivers will perform all the tasks, most will perform at least one. Each task is accompanied by a code snippet to help you implement it in your driver.

enum {

    kMyOffPowerState  = 0,

    kMyIdlePowerState   = 1,

    kMyOnPowerState = 2

};

static IOPMPowerState myPowerStates[3] = {

    {1, kMyOffPowerState, kMyOffPowerState, kMyOffPowerState, 0, 0, 0, 0, 0, 0, 0, 0},

    {1,kIOPMPowerOn, kIOPMPowerOn, kIOPMPowerOn, 0, 0, 0, 0, 0, 0, 0, 0},

    {1,kIOPMPowerOn, kIOPMPowerOn, kIOPMPowerOn, 0, 0, 0, 0, 0, 0, 0, 0}

};

bool PMExampleDriver::start(IOService * provider)

{

   /*

    * Create a work loop and set up synchronization

    * using a command gate.

    */

    fWorkloop = IOWorkLoop::workLoop();

    fGate = IOCommandGate::commandGate(this);

    if (fGate && fWorkloop) {

        fWorkloop->addEventSource(fGate);

    }

     * Initialize power management, join the power plane,

     * and register with power management.

     */

    PMinit();

    provider->joinPMtree(this);

    registerPowerDriver(this, myPowerStates, 3);

}

enum {

    kMyOffState = 0,

    kMyOnState = 1

};

/*

 * Make sure the hardware is in the ON state

 * before accessing it. If it's powered off, call changePowerStateToPriv

 * to put the device in the ON state.

 */

if (getPowerState() == kMyOnState)

{

    /* Device is ON. OK to access hardware. */

} else {

    changePowerStateToPriv( kMyOnState );

    /*

     * Note: If your device has been powered off for a system sleep, you cannot

     * try to adjust your power state upwards. You are locked in your OFF or

     * low-power state until system power is restored on wake.

     */

    /*

     * Although changePowerStateToPriv returns immediately,

     * it is _NOT_ safe to touch the hardware yet. You must wait until you

     * receive your setPowerState() call before you can safely modify

     * the hardware.

     */

}

void MyExampleDriver::systemWillShutdown( IOOptionBits specifier )

{

    if ( kIOMessageSystemWillPowerOff == specifier ) {

        // System is shutting down; perform appropriate processing.

    } else if ( kIOMessageSystemWillRestart == specifier ) {

        // System is restarting; perform appropriate processing.

    }

    /*

     * You must call your superclass's implementation of systemWillShutdown as

     * soon as you're finished processing your shutdown or restart

     * because the shutdown will not proceed until you do.

     */

    super::systemWillShutdown( specifier );

}

// timeToStayOn is a length of time in milliseconds.

clampPowerOn ( timeToStayOn );