March 29, 2008 PMF 9

### NAME

PMF, pmf_device_register, pmf_device_deregister, pmf_device_suspend, pmf_device_resume, pmf_device_recursive_suspend, pmf_device_recursive_resume, pmf_device_resume_subtree, pmf_class_network_register, pmf_class_input_register, pmf_class_display_register, pmf_system_suspend, pmf_system_resume, pmf_system_shutdown, pmf_event_register, pmf_event_deregister, pmf_event_inject, pmf_set_platform, pmf_get_platform - power management and inter-driver messaging framework

### SYNOPSIS

```bool` pmf_device_register(```device_t dev``, bool (*suspend)(device_t dev)``, bool (*resume)(device_t dev)`) pmf_device_register1(```device_t dev``, bool (*suspend)(device_t dev)``, bool (*resume)(device_t dev)``, bool (*shutdown)(device_t dev, int how)`)
```void` pmf_device_deregister(```device_t dev`)
```bool` pmf_device_suspend(```device_t dev`)
```bool` pmf_device_resume(```device_t dev`)
```bool` pmf_device_recursive_suspend(```device_t dev`)
```bool` pmf_device_recursive_resume(```device_t dev`)
```bool` pmf_device_resume_subtree(```device_t dev`)
```void` pmf_class_network_register(```device_t dev``, struct ifnet *ifp`)
```bool` pmf_class_input_register(```device_t dev`)
```bool` pmf_class_display_register(```device_t dev`)
```bool` pmf_system_suspend(```void`)
```bool` pmf_system_resume(```void`)
```void` pmf_system_shutdown(```int`)
```bool` pmf_event_register(```device_t dev``, pmf_generic_event_t ev``, void (*handler)(device_t dev)``, bool global`)
```void` pmf_event_deregister(```device_t dev``, pmf_generic_event_t ev``, void (*handler)(device_t dev)``, bool global`)
```bool` pmf_event_inject(```device_t dev``, pmf_generic_event_t ev`)
```bool` pmf_set_platform(```const char *key``, const char *value`)
```const` `char``*` pmf_get_platform(```const char *key`)

### DESCRIPTION

The machine-independent PMF framework provides power management and inter-driver messaging support for device drivers.

### DATA TYPES

Drivers for devices implementing PMF may make use of the following data type:

```pmf_generic_event_t`
  A device driver can register as a listener for specific events, or inject events into the message queue. The following message types are defined:
    ```PMFE_DISPLAY_ON`
    ```PMFE_DISPLAY_REDUCED`
    ```PMFE_DISPLAY_STANDBY`
    ```PMFE_DISPLAY_SUSPEND`
    ```PMFE_DISPLAY_OFF`
    ```PMFE_DISPLAY_BRIGHTNESS_UP`
    ```PMFE_DISPLAY_BRIGHTNESS_DOWN`
    ```PMFE_AUDIO_VOLUME_DOWN`
    ```PMFE_AUDIO_VOLUME_TOGGLE`
    ```PMFE_CHASSIS_LID_CLOSE`
    ```PMFE_CHASSIS_LID_OPEN`

### FUNCTIONS

pmf_device_register(```dev``, suspend``, resume`)
  Register a device with the power management framework. If either ```suspend` or ```resume` is ```NULL` then it is assumed that device state does not need to be captured and resumed on a power transition. Bus and class-level power management will still be performed. Returns ```false` if there was an error.

pmf_device_register1(```dev``, suspend``, resume``, shutdown`)
  Like pmf_device_register, but additionally registers a shutdown handler.

pmf_device_deregister(```dev`)
  Deregister a device with the power management framework.

pmf_device_suspend(```dev`)
  Suspend a device by first calling the class suspend handler, followed by the driver suspend handler, and finally the bus suspend handler.

pmf_device_resume(```dev`)
  Resume a device by first calling the bus resume handler, followed by the driver resume handler, and finally the class resume handler.

pmf_device_recursive_suspend(```dev`)
  As pmf_device_suspend(``), but ensures that all child devices of ```dev` are suspended.

pmf_device_recursive_resume(```dev`)
  As pmf_device_resume(``), but ensures that all parent devices of ```dev` are resumed.

pmf_device_resume_subtree(```dev`)
  As pmf_device_resume(``), but ensures that all child devices of ```dev` are resumed.

pmf_class_network_register(```dev``, ifp`)
  Register a device with the power management framework as a network-class device.

pmf_class_input_register(```dev`)
  Register a device with the power management framework as an input-class device.

pmf_class_display_register(```dev`)
  Register a device with the power management framework as a display-class device.

pmf_system_suspend(```void`)
  Suspend all attached devices. Devices are suspended by traversing the autoconfiguration tree beginning with the leaf nodes. This function will fail if any attached drivers do not support the power management framework.

pmf_system_resume(```void`)
  Resume all attached devices. Devices are resumed by traversing the autoconfiguration tree beginning with devices that do not have a parent. This function will fail if any attached drivers do not support the power management framework.

pmf_system_shutdown(```int`)
  Shutdown all attached devices. Devices are shut down by traversing the autoconfiguration tree beginning with the leaf nodes. The integer argument is passed to the driver shutdown functions. It should contain the reboot(2) ``howto'' argument. This function ignores the presence of attached drivers that do not support the power management framework.

pmf_event_register(```dev``, ev``, handler``, global`)
  Register the callback ```handler` to be called whenever an ```ev` event is triggered. If ```global` is ```true`, ```handler` accepts anonymous events from pmf_event_inject(``).

pmf_event_deregister(```dev``, ev``, handler``, global`)
  Deregister the callback previously registered with pmf_event_register(``).

pmf_event_inject(```dev``, ev`)
  Inject an inter-driver message into the message queue. If ```dev` is ```NULL`, the event is considered to be anonymous and one or more drivers may handle this event, otherwise the event is delivered directly to the callback registered by ```dev`.

pmf_set_platform(```key``, value`)
  Insert a name-value pair into the platform information database.

pmf_get_platform(```key`)
  Retrieve the value for ```key` from the platform information database. Returns ```NULL` if the key is not present.

### CODE REFERENCES

This section describes places within the NetBSD source tree where actual code implementing or using the power management framework can be found. All pathnames are relative to ```/usr/src`.

The power management framework is implemented within the files ```sys/sys/pmf.h`, ```sys/sys/device.h`, ```sys/kern/kern_pmf.c`, and ```sys/kern/subr_autoconf.c`.

### SEE ALSO

autoconf(9), driver(9)

### HISTORY

The PMF framework appeared in NetBSD5.0.

### AUTHORS

Jared D. McNeill <jmcneill@NetBSD.org>
Joerg Sonnenberger <joerg@NetBSD.org>