System Power Management Model

This section describes the details of the System Power Management model. The model includes the following components:

• Autoshutdown threshold

• Busy state

• Hardware state

• Policy

• Power management entry points

Autoshutdown Threshold

The system may be shut down (powered off) automatically after a configurable period of idleness. This period is known as the autoshutdown threshold. This behavior is enabled by default for SPARC desktop systems first shipped after October 1, 1995 and before July 1, 1999. It may be overridden using dtpower(1M) or power.conf(4).

Busy State

There are several ways to measure the busy state of the system. The currently supported built-in metrics are keyboard characters, mouse activity, tty characters, load average, disk reads, and NFS requests. Any one of these may make the system busy. In addition to the built-in metrics, an interface is defined for running a user-specified process that may indicate that the system is busy.

Hardware State

Devices that export a reg property are considered to have hardware state that must be saved prior to shutting down the system. A device that does not have a reg property is considered to be stateless. However, this consideration can be overridden by the device driver.

A device that has hardware state but no reg property (such as a SCSI target driver, which has hardware at the other end of the SCSI bus), is called to save and restore its state if it exports a pm-hardware-state property with the value needs-suspend-resume. Otherwise, the lack of a reg property is taken to mean that the device has no hardware state. For information on device properties, see Chapter 4, Properties and Events.

A device that has a reg property but no hardware state may export a pm-hardware-state property with the value no-suspend-resume to keep the framework from calling into the driver to save and restore that state. For more information on power management properties, see the pm-components(9P) man page.

Automatic Power Management for Systems

The system will be shut down if the following conditions apply:

• Autoshutdown is enabled by dtpower(1M) or power.conf(4).

• The system has been idle for autoshutdown threshold minutes.

• All the metrics specified in power.conf(4) have been satisfied.

Entry Points Used by System Power Management

System power management passes the command DDI_SUSPEND to the detach(9E) driver entry point to request the driver to save the device hardware state. It passes the command DDI_RESUME to the attach(9E) driver entry point to request the driver to restore the device hardware state.

detach() Entry Point

The syntax for detach(9E) is as follows:

    int detach(dev_info_t *dip, ddi_detach_cmd_t cmd);

If a device has a reg property or a pm-hardware-state property with a value of needs-suspend-resume, then the framework calls into the driver's detach(9E) entry point to allow the driver to save the hardware state of the device to memory so that it can be restored after the system power returns. To process the DDI_SUSPEND command, detach(9E) must do the following:

• Block further operations from being initiated until the device is resumed (except for dump(9E) requests).

• Wait until outstanding operations have completed (or abort them if they can be restarted).

• Cancel pending timeouts and callbacks.

• Save any volatile hardware state to memory. The state includes the contents of device registers, and may also include downloaded firmware.

If for some reason the driver is not able to suspend the device and save its state to memory, then it must return DDI_FAILURE, and the framework aborts the system power management operation.

In some cases, powering down a device involves certain risks. For example, if a tape drive is powered off with a tape inside it, the tape can be damaged. In such a case, attach(9E) should:

• Call ddi_removing_power(9F) to determine if a DDI_SUSPEND command may cause power to be removed from the device.

• Determine if power removal will cause problems.

Dump requests must be honored. The framework uses the dump(9E) entry point to write out the state file containing the contents of memory. See the dump(9E) man page for restrictions imposed on the device driver when using this entry point.

If the device implements power-manageable components, the device may have had its state saved and powered off when its detach(9E) entry point is called with the DDI_SUSPEND command. In this case the driver should cancel pending timeouts and suppress the call to pm_raise_power(9F) (except for dump(9E) requests) until the device is resumed by a call to attach(9E) with a command of DDI_RESUME. The driver must keep sufficient track of its state to be able to deal appropriately with this possibility. Example 9-6 shows an example of a detach(9E) routine with the DDI_SUSPEND command implemented.

Example 9-6 detach(9E) Routine Implementing DDI_SUSPEND

int
xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd)
{
        struct xxstate *xsp;
        int instance;

        instance = ddi_get_instance(dip);
        xsp = ddi_get_soft_state(statep, instance);

        switch (cmd) {
        case DDI_DETACH:
          ...

        case DDI_SUSPEND:
               /*
                * We do not allow DDI_SUSPEND if power will be removed and
                * we have a device that damages tape when power is removed
                * We do support DDI_SUSPEND for Device Reconfiguration.
.
                */
                  if (ddi_removing_power(dip) && xxdamages_tape(dip))
                     return (DDI_FAILURE);

                mutex_enter(&xsp->mu);
                xsp->xx_suspended = 1;  /* stop new operations */

                /*
                 * Sleep waiting for all the commands to be completed
                 */
                ...

                /*
                 * If a callback is outstanding which cannot be cancelled
                 * then either wait for the callback to complete or fail the
                 * suspend request
                 */
                ...

                /*
                 * This section is only needed if the driver maintains a
                 * running timeout
                 */
                if (xsp->xx_timeout_id) {
                        timeout_id_t temp_timeout_id = xsp->xx_timeout_id;

                        xsp->xx_timeout_id = 0;
                        mutex_exit(&xsp->mu);
                        untimeout(temp_timeout_id);
                        mutex_enter(&xsp->mu);
                }

                if (!xsp->xx_state_saved) {
                        /*
                         * Save device register contents into
                         * xsp->xx_device_state
                         */
                        ...
                }
                mutex_exit(&xsp->mu);
                return (DDI_SUCCESS);

        default:
                return (DDI_FAILURE);
}