Inside Macintosh: Devices /

Chapter 6 - Power Manager

About the Power Manager

Battery-operated Macintosh computers (also known as portable Macintosh computers) draw power from a built-in battery that can be charged from a voltage converter plugged into an electric socket. In order to prolong the battery charge and thereby increase the amount of time the computer can be operated from the battery, portable Macintosh computers contain software and hardware components that can put the computer into various power conservation states, known as the power-saver, idle, and sleep states.

The software that controls power to the internal devices of portable Macintosh computers is the Power Manager. The Power Manager provides a software interface to the available power controlling hardware. On the Macintosh Portable computer, the power-management hardware is the 50753 microprocessor (known as the Power Manager integrated circuit or Power Manager IC). On other portable Macintosh computers, other hardware may be used.

The Power Manager also provides some services unique to portable Macintosh computers--such as reading the current clock speed--that are not directly related to power control. The power management circuits and the microcode in the on-chip ROM of the Power Manager IC are described in the Guide to the Macintosh Family Hardware, second edition. The Power Manager provides routines that your program can use to enable and disable the idle state, to control power to some of the subsystems of the computer, and to ensure that your program is not adversely affected when the Power Manager puts the computer into the sleep state.

The power-saver state is a low power-consumption state of several portable Macintosh computers in which the processor slows from its normal clock speed to some slower clock speed. On the PowerBook 170 computer, for example, the CPU clock speed can be reduced from 25 MHz to 16 MHz in order to conserve power.

In the idle state, the Power Manager slows the computer even further, from its current clock speed to a 1 MHz clock speed. The Power Manager puts a portable Macintosh computer in the idle state when the system has been inactive for 15 seconds. When the computer has been inactive for an additional period of time (the user can set the length of this period), the Power Manager and the various device drivers shut off power or remove clocks from the computer's various subsystems, including the CPU, RAM, ROM, and I/O ports. This condition is known as the sleep state.

No data is lost from RAM when a portable Macintosh computer is in the sleep state. Most applications can be interrupted by the idle and sleep states without any adverse effects. When the user resumes use of the computer (by pressing a key, for example), most of the applications that were running before the computer entered the sleep state are still loaded in memory and resume running as if nothing had happened. If your application or device driver cannot tolerate the sleep state, however, you can add an entry to an operating-system queue called the sleep queue. The Power Manager calls every sleep queue routine before the computer goes into the sleep state.

The user can also use the Battery desk accessory or a Finder menu item to cause a portable Macintosh computer to go into the sleep state immediately. If the user chooses Sleep from the Battery desk accessory (or from the Special menu in the Finder), the Power Manager checks to see if any network communications will be interrupted by going into the sleep state. If network communications will be affected, a built-in sleep procedure displays a dialog box (shown in Figure 6-1) giving the user the option of canceling the Sleep command.

Figure 6-1 A network driver's sleep dialog box

Note

Some portable Macintosh computers (for example, the Macintosh Portable) do not have a power switch. On these computers, if the user chooses Shut Down from Special menu in the Finder, the Power Manager puts the computer into the sleep state regardless of whether any network communication routines are running at the time.

The power management circuits in portable Macintosh computers include a battery-voltage monitor, a voltage regulator and battery-charging circuit, and (on certain portable computers) the Power Manager IC. The Power Manager IC controls the clocks and power lines to the various internal components and external ports of the computer. The microcode in the Power Manager IC implements many of the computer's power management features, such as power and clock control and the wakeup timer. A user or an application can set the wakeup timer to return the computer from the sleep state to the operating state at a specific time.

Note

The wakeup timer is not available on all portable Macintosh computers.

The Power Manager firmware in the ROM of the computer provides an interface that allows your application to control some of the functions of the power control hardware. The power management hardware charges the battery, provides the voltages needed by the system, and automatically shuts down all power and clocks to the system if the battery voltage falls below a certain threshold. The automatic shutdown function helps to prevent possible damage to the battery resulting from low voltage.

At any given time, a portable Macintosh computer is in one of five power-consumption states:

• normal state
• power-saver state
• idle state
• sleep state
• shutdown state

When the computer is in its normal state, the CPU is running at its full clock speed and no measures are being taken to conserve power. The computer behaves exactly like any Macintosh computer that is not operated from a battery. Similarly, the shutdown state on a portable Macintosh computer is exactly like the shutdown state on any nonportable Macintosh computer, except that there is a very small drain on the battery to maintain the settings of the computer's parameter RAM.

The following sections provide more information about the three power conservation states (power-saver, idle, and sleep) managed by the Power Manager.

IMPORTANT

The exact implementation details--and indeed the very existence of one or more of the three power conservation states--is subject to variation across the entire line of portable Macintosh computers. In general, your application or other software should not be affected by any such variations.

The Power-Saver State

The power-saver state, available on some portable Macintosh computers, is a power conservation state in which the processor slows from its normal clock speed to some slower clock speed. On the PowerBook 180 computer, for example, the user can use the PowerBook control panel to reduce the CPU clock speed from 33 MHz to 16 MHz.

There is currently no way for your application to put a portable Macintosh computer into the power-saver state or to return it to the normal (full-speed) state. Moreover, the power-saver state is not available on all portable Macintosh computers. If the operation of your application or other software component depends on the CPU clock speed, you can use the Power Manager's GetCPUSpeed function to determine the current speed. In general, of course, it's best to design your application so that it is unaffected by any changes in the clock speed of the CPU.

The Idle State

When a portable Macintosh computer has been inactive for some amount of time, the Power Manager causes the CPU to insert wait states into each RAM or ROM access. On the Macintosh Portable, for example, after 15 seconds of inactivity the Power Manager inserts 64 wait states, effectively changing the clock speed from 16 MHz to 1 MHz. This condition is referred to as the idle state or the rest state.

Note

The inactivity timeout interval, clock speed, and hardware implementation of the idle state are subject to variation across the entire line of portable Macintosh computers.

For the purposes of determining whether to enter the idle state, inactivity is defined as the absence of any of the following:

• any execution of the PBRead or PBWrite function by the File Manager or Device Manager
• a call to the Event Manager's PostEvent or OSEventAvail function
• any access of the Apple Sound Chip (ASC) or other sound-producing hardware
• completion of an Apple Desktop Bus (ADB) transaction
• a call to the QuickDraw SetCursor procedure that changes the cursor
• the cursor displayed as the watch cursor

The Power Manager enters the idle state in one of two ways, depending on whether the computer supports a mode of idling called power cycling. If power cycling is available (for example, in the PowerBook 140 and later models), the CPU is turned off after two seconds of inactivity. After a short interval (on the order of one-half to three-fourths of a second), power is restored to the CPU. The Operating System then checks to see whether any relevant activity has occurred. If it has, the power cycling is stopped and the computer returns to the normal operating state. If, however, no activity has occurred, power cycling resumes with a slightly longer interval (up to several seconds). The CPU remains off for the duration of the cycling or until an interrupt occurs.

If power cycling is not available, the Power Manager uses an alternate method of entering the idle state. The Power Manager maintains an activity timer that measures the amount of time that has elapsed since the last relevant system activity. The activity timer is originally set to 15 seconds. When the timer counts down to 0, the Power Manager puts the computer into the idle state. Whenever the Power Manager detects one of the relevant forms of activity, it resets the activity timer to 15 seconds and, if the computer is in the idle state, returns the computer to the operating state.

Neither the user nor your application can change the activity timer to use a period other than 15 seconds. However, the user can disable the activity timer through the Portable or PowerBook control panel, and your application can reset, enable, and disable the activity timer by using the IdleUpdate, EnableIdle, and DisableIdle routines. Your application can also use the GetCPUSpeed function to determine whether the computer is currently in the idle state. See "Enabling or Disabling the Idle State," beginning on page 6-15, for a further discussion of these routines.

The Sleep State

The Operating System sends a sleep command to the power management hardware when the user requests it (through the Battery desk accessory or the Finder), when the battery voltage falls below a preset level, or when the system has remained inactive for an amount of time that the user sets through the Portable or PowerBook control panel.

The Operating System uses the power management hardware to shut down power to the CPU, the ROM, and some of the control logic. Sufficient power is maintained to the RAM so that no data is lost. Before the Operating System sends the sleep command to the power management hardware, it performs the following tasks:

• It pushes the contents of all of the CPU's internal registers onto the stack.
• It calls all sleep procedures listed in the sleep queue to inform them that the system is about to be put into the sleep state. These procedures include the device drivers for the serial ports and floppy disk drives. Each device driver must call the power management hardware to stop power or clocks to the peripheral device controlled by that driver. If the device contains any internal registers, the device driver must save their contents before turning off power to the device. The sleep queue is described in the following section, "The Sleep Queue."
• It pushes onto the stack the Reset vector, the contents of the versatile interface adapter (VIA) chip, and the contents of the Apple Sound Chip (ASC) control registers.
• It saves the stack pointer in memory.

While a portable Macintosh computer is in the sleep state, the clock to the power management hardware (for example, the Power Manager IC) is off so that the hardware does no processing. On each rising edge of the 60 Hz clock signal (from one of the computer's logic chips), a hardware circuit restores the clock signal to the power management hardware, which updates the time in the real-time clock and checks the status of the system to determine whether to return the computer to its operating state. The power management hardware checks for the existence of the following conditions:

• A key on the keyboard has been pressed.
• The wakeup timer is enabled and the time to which the wakeup timer is set equals the time in the real-time clock.
• An internal modem is installed, the user has activated the ring-detect feature, and the modem has detected a ring (that is, someone has called the modem).

Note that use of the mouse or trackball cannot be detected by the power management hardware.

If the power management hardware does not detect any of these conditions, it deactivates its own clock until the next rising edge of the 60 Hz clock signal. If the power management hardware does detect one of these conditions, it restores power to the CPU, ROM, and any other hardware that was running when the computer entered the sleep state. Then the Power Manager's wakeup procedure reverses the procedure that put the computer into the sleep state, including calling each routine listed in the sleep queue to allow it to restore power to any subsystems it controls.

The Sleep Queue

The Power Manager maintains an operating-system queue called the sleep queue. The sleep queue contains pointers to all of the routines--called sleep procedures--that the Power Manager must call before it puts the computer into the sleep state or returns it to the operating state. Each device driver, for example, can place in the sleep queue a pointer to a routine that controls power to the subsystem that the driver controls. When the Power Manager is ready to put the computer into the sleep state, it calls each of the sleep procedures listed in the sleep queue. Each procedure performs whatever tasks are necessary to prepare for the sleep state, including calling Power Manager routines, and then returns control to the Power Manager. Similarly, the Power Manager calls each sleep procedure when it is returning the computer to the operating state.

If you are writing a device driver or if you want your program to be informed before the computer enters the sleep state, you can place an entry for your sleep procedure in the sleep queue. If you do place an entry in the sleep queue, remember to remove it before your device driver or application terminates. You use the SleepQInstall and SleepQRemove procedures to install and remove sleep queue entries, as described in "Installing a Sleep Procedure," beginning on page 6-18.

Your sleep procedure can be called at any of four different times, namely

• when the Power Manager wants to know whether it may put the computer into the sleep state (a sleep request)
• when the Power Manager is about to put the computer into the sleep state (a sleep demand)
• when the Power Manager has just returned the computer to the normal operating state (a wakeup demand)
• when the Power Manager has decided not to put the computer into the sleep state but has already issued a sleep request (a sleep-request revocation)

Your sleep procedure will need to respond differently, depending on the reason it is being called. The following four sections describe these cases.

Sleep Requests

The Power Manager sends your sleep procedure a sleep request when it would like to put the computer into the sleep state. Your sleep procedure then has the option of denying the sleep request. If any procedure in the sleep queue denies the sleep request, the Power Manager sends a sleep-request revocation to each routine that it has already called with a sleep request, and the computer does not enter the sleep state. If, on the other hand, every sleep procedure in the sleep queue accepts the sleep request, then the Power Manager sends a sleep demand to each sleep procedure in the sleep queue. After every sleep procedure has processed the sleep demand, the Power Manager puts the computer into the sleep state.

Before sending a sleep request to any of the sleep procedures in the sleep queue, the Power Manager calls a built-in sleep procedure that checks the status of certain network services, as summarized in Table 6-1. Only if all of the network services permit sleep does the Power Manager continue by sending sleep requests to the routines in the sleep queue. The network services in Table 6-1 are described in Inside Macintosh:Networking.

The Power Manager issues a sleep request when a sleep timeout occurs (that is, when the period of inactivity set by the user in the Portable or PowerBook control panel has expired).

Table 6-1 Response of network services to sleep requests and sleep demands

Network service in use	Response to sleep request	Response to conditional sleep demand	Response to unconditional sleep demand
.MPP low-level protocol (DDP, NBP, RTMP, AEP)	Close driver if computer is on battery; else deny request	Close driver if user gives okay; else deny request	Close driver
.XPP extended protocol (ASP, AFP); no server volume mounted	Close driver if computer is on battery; else deny request	Close driver if user gives okay; else deny request	Close driver
.XPP; server volume mounted	Deny request	Close server sessions and close driver if user gives okay; else deny request	Close server sessions and close driver
An application is currently using AppleTalk	Deny request	Close server sessions and close driver if user gives okay; else deny request	Close server sessions and close driver

Sleep Demands

The Power Manager sends your sleep procedure a sleep demand when it is about to put the portable Macintosh computer into the sleep state. When a procedure in the sleep queue receives a sleep demand, it must prepare for the sleep state as quickly as possible and return control to the Power Manager.

From the point of view of the Power Manager, there are two types of sleep demands--conditional and unconditional. The Power Manager might cancel a conditional sleep demand if certain network services are in use; an unconditional sleep demand cannot be canceled. When your sleep procedure receives a sleep demand, however, your procedure has no way to determine whether it originated as a conditional sleep demand or an unconditional sleep demand. Your device driver or application must prepare for the sleep state and return control promptly to the Power Manager when it receives a sleep demand.

The Power Manager processes a conditional sleep demand when the user chooses Sleep from the Battery desk accessory or from the Special menu in the Finder. When the Power Manager processes a conditional sleep demand, it first sends a sleep request to the network driver's sleep procedure (see Table 6-1). Whenever one of the network services is in use, the sleep procedure displays a dialog box requesting the user's permission to put the computer into the sleep state. The wording of the message in the dialog box depends on the nature of the network service in use. For example, if an .XPP driver protocol is in use, has opened a server, and has mounted a volume, then the message warns the user that the volume will be closed when the computer is put into the sleep state.

If the user denies permission to close the driver, the Power Manager does not send sleep demands to the routines in the sleep queue. If the user does give permission to close the driver, the Power Manager sends a sleep demand to the network driver's sleep procedure and then to every other sleep procedure in the sleep queue.

The Power Manager issues an unconditional sleep demand when the battery voltage falls below a preset level or when the user chooses Shut Down from the Special menu in the Finder. In this case, the Power Manager sends a sleep demand to the network driver's sleep procedure, which closes all network drivers. Then the Power Manager sends a sleep demand to every other sleep procedure in the sleep queue. As always for a sleep demand, each sleep procedure must prepare for the sleep state and return control to the Power Manager as quickly as possible. In this case, the Power Manager does not display any warnings or dialog boxes; neither the network services, the user, nor any application can deny the sleep demand.

Wakeup Demands

After restoring full power to the CPU, RAM, and ROM, the Power Manager's wakeup procedure calls each sleep procedure in the sleep queue with a wakeup demand. A wakeup demand informs your sleep procedure that it must reverse whatever steps it followed when it prepared for the sleep state. For example, a database application might reestablish communications with a remote database.

Sleep-Request Revocations

If any sleep procedure in the sleep queue denies a sleep request, the Power Manager sends a sleep-request revocation to every sleep procedure that it has already called with a sleep request. Your sleep procedure must reverse whatever steps it followed when it prepared to receive a sleep demand. A communications application that prevents users from opening new sessions while it is waiting to receive a sleep demand, for example, might once again allow users to open new sessions.

Power Manager Dispatch

Software that reads and writes directly to the Power Manager's private data structures and parameter RAM must be updated any time Apple Computer, Inc. makes a change to the internal operation of the Power Manager. The Power Manager for some versions of the Macintosh Operating System includes routines--referred to as the Power Manager dispatch routines--that eliminate the need for applications to deal directly with the
Power Manager's data structures. These routines provide access to most of the Power Manager's internal parameters. The interface is extensible, and may grow over time to accommodate new kinds of functions.

You can use the routines described in "Power Manager Dispatch Routines," beginning on page 6-40, to isolate your application from future changes to the internal operation of the Power Manager software.

IMPORTANT

Apple Computer, Inc. reserves the right to change the internal operation of the Power Manager software. Applications should not depend on the Power Manager's internal data structures or parameter RAM.

You should not depend on the Power Manager's internal data structures staying the same in future versions of system software. In particular, do not assume that

• timeout values such as the hard disk spindown time reside at the same locations in parameter RAM
• the power cycling process works the same way or uses the same parameters
• direct commands to the Power Manager microcontroller are supported in all models

Note

Whereas the Pascal programming language interface is used to describe the Power Manager routines in "Power Manager Routines," beginning on page 6-28, the C language interface is used for the newer routines described in "Power Manager Dispatch Routines," beginning on page 6-40. The section "Summary of the Power Manager," beginning on page 6-67, includes both Pascal and C interfaces for both sets of routines.