NAME
PMF,
pmf_device_register,
pmf_device_register1,
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
#include <sys/device.h>
bool
pmf_device_register(
device_t
dev,
bool
(*suspend)(device_t dev, const pmf_qual_t *qual),
bool (*resume)(device_t dev,
const pmf_qual_t *qual));
bool
pmf_device_register1(
device_t
dev,
bool
(*suspend)(device_t dev, const pmf_qual_t *qual),
bool (*resume)(device_t dev,
const pmf_qual_t *qual),
bool (*shutdown)(device_t dev,
int how));
void
pmf_device_deregister(
device_t
dev);
bool
pmf_device_suspend(
device_t
dev,
const pmf_qual_t
*qual);
bool
pmf_device_resume(
device_t
dev,
const pmf_qual_t
*qual);
bool
pmf_device_recursive_suspend(
device_t
dev,
const pmf_qual_t
*qual);
bool
pmf_device_recursive_resume(
device_t
dev,
const pmf_qual_t
*qual);
bool
pmf_device_subtree_resume(
device_t
dev,
const pmf_qual_t
*qual);
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(
const
pmf_qual_t *qual);
bool
pmf_system_resume(
const
pmf_qual_t *qual);
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_qual_t
- An opaque aggregate of qualifications on a
PMF suspend or resume call.
-
-
- 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_UP
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. The
suspend and resume functions
are passed dev and a
pmf_qual_t, and will be called when the system state
changes; they should return
true
on success and
false
on failure. 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. During system shutdown,
pmf_system_shutdown() calls
shutdown on dev with the
reboot(2)
“howto” in the second argument. shutdown
should return
true
on success and
false
on failure.
-
-
- pmf_device_deregister(dev)
- Deregister a device with the power management
framework.
-
-
- pmf_device_suspend(dev,
qual)
- 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,
qual)
- 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,
qual)
- As pmf_device_suspend(), but ensures that
all child devices of dev are suspended.
-
-
- pmf_device_recursive_resume(dev,
qual)
- As pmf_device_resume(), but ensures that
all parent devices of dev are resumed.
-
-
- pmf_device_subtree_resume(dev,
qual)
- 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(qual)
- 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(qual)
- 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
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
NetBSD
5.0.
AUTHORS
Jared D. McNeill
<
jmcneill@NetBSD.org>
Joerg Sonnenberger
<
joerg@NetBSD.org>