test

Writing Device Drivers

Device Power Management

The following summary lists what your driver needs to do to power manage a USB device. A more detailed description of power management follows this summary.

  1. Create power management components during attach(9E). See the usb_create_pm_components(9F) man page.

  2. Implement the power(9E) entry point.

  3. Call pm_busy_component(9F) and pm_raise_power(9F) before accessing the device.

  4. Call pm_idle_component(9F) when finished accessing the device.

The USBA 2.0 framework supports four power levels as specified by the USB interface power management specification. See /usr/include/sys/usb/usbai.h for information on mapping USB power levels to operating system power levels.

The hubd driver suspends the port when the device goes to the USB_DEV_OS_PWR_OFF state. The hubd driver resumes the port when the device goes to the USB_DEV_OS_PWR_1 state and above. Note that port suspend is different from system suspend. In port suspend, only the USB port is shut off. System suspend is defined in System Power Management.

The client driver might choose to enable remote wakeup on the device. See the usb_handle_remote_wakeup(9F) man page. When the hubd driver sees a remote wakeup on a port, the hubd driver completes the wakeup operation and calls pm_raise_power(9F) to notify the child.

The following figure shows the relationship between the different pieces of power management.

Figure 20–5 USB Power Management

Diagram shows when to employ two different power management schemes.

The driver can implement one of the two power management schemes described at the bottom of Figure 20–5. The passive scheme is simpler than the active scheme because the passive scheme does not do power management during device transfers.

Active Power Management

This section describes the functions you need to use to implement the active power management scheme.

Do the following work in the attach(9E) entry point for your driver:

  1. Call usb_create_pm_components(9F).

  2. Optionally call usb_handle_remote_wakeup(9F) with USB_REMOTE_WAKEUP_ENABLE as the second argument to enable a remote wakeup on the device.

  3. Call pm_busy_component(9F).

  4. Call pm_raise_power(9F) to take power to the USB_DEV_OS_FULL_PWR level.

  5. Communicate with the device to initialize the device.

  6. Call pm_idle_component(9F).

Do the following work in the detach(9E) entry point for your driver:

  1. Call pm_busy_component(9F).

  2. Call pm_raise_power(9F) to take power to the USB_DEV_OS_FULL_PWR level.

  3. If you called the usb_handle_remote_wakeup(9F) function in your attach(9E) entry point, call usb_handle_remote_wakeup(9F) here with USB_REMOTE_WAKEUP_DISABLE as the second argument.

  4. Communicate with the device to cleanly shut down the device.

  5. Call pm_lower_power(9F) to take power to the USB_DEV_OS_PWR_OFF level.

    This is the only time a client driver calls pm_lower_power(9F).

  6. Call pm_idle_component(9F).

When a driver thread wants to start I/O to the device, that thread does the following tasks:

  1. Call pm_busy_component(9F).

  2. Call pm_raise_power(9F) to take power to the USB_DEV_OS_FULL_PWR level.

  3. Begin the I/O transfer.

The driver calls pm_idle_component(9F) when the driver receives notice that an I/O transfer has completed.

In the power(9E) entry point for your driver, check whether the power level to which you are transitioning is valid. You might also need to account for different threads calling into power(9E) at the same time.

The power(9E) routine might be called to take the device to the USB_DEV_OS_PWR_OFF state if the device has been idle for some time or the system is shutting down. This state corresponds to the PWRED_DWN state shown in Figure 20–4. If the device is going to the USB_DEV_OS_PWR_OFF state, do the following work in your power(9E) routine:

  1. Put all open pipes into the idle state. For example, stop polling on the interrupt pipe.

  2. Save any device or driver context that needs to be saved.

    The port to which the device is connected is suspended after the call to power(9E) completes.

The power(9E) routine might be called to power on the device when either a device-initiated remote wakeup or a system-initiated wakeup is received. Wakeup notices occur after the device has been powered down due to extended idle time or system suspend. If the device is going to the USB_DEV_OS_PWR_1 state or above, do the following work in your power(9E) routine:

  1. Restore any needed device and driver context.

  2. Restart activity on the pipe that is appropriate to the specified power level. For example, start polling on the interrupt pipe.

If the port to which the device is connected was previously suspended, that port is resumed before power(9E) is called.

Passive Power Management

The passive power management scheme is simpler than the active power management scheme described above. In this passive scheme, no power management is done during transfers. To implement this passive scheme, call pm_busy_component(9F) and pm_raise_power(9F) when you open the device. Then call pm_idle_component(9F) when you close the device.