311 lines
9.1 KiB
Groff
311 lines
9.1 KiB
Groff
.\" $NetBSD: pmf.9,v 1.23 2024/03/09 05:22:05 riastradh Exp $
|
|
.\"
|
|
.\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd March 9, 2024
|
|
.Dt PMF 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm PMF ,
|
|
.Nm pmf_device_register ,
|
|
.Nm pmf_device_register1 ,
|
|
.Nm pmf_device_deregister ,
|
|
.Nm pmf_device_suspend ,
|
|
.Nm pmf_device_resume ,
|
|
.Nm pmf_device_recursive_suspend ,
|
|
.Nm pmf_device_recursive_resume ,
|
|
.Nm pmf_device_resume_subtree ,
|
|
.Nm pmf_class_network_register ,
|
|
.Nm pmf_class_input_register ,
|
|
.Nm pmf_class_display_register ,
|
|
.Nm pmf_system_suspend ,
|
|
.Nm pmf_system_resume ,
|
|
.Nm pmf_system_shutdown ,
|
|
.Nm pmf_event_register ,
|
|
.Nm pmf_event_deregister ,
|
|
.Nm pmf_event_inject ,
|
|
.Nm pmf_set_platform ,
|
|
.Nm pmf_get_platform
|
|
.Nd power management and inter-driver messaging framework
|
|
.Sh SYNOPSIS
|
|
.In sys/device.h
|
|
.Ft bool
|
|
.Fn 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)"
|
|
.Ft bool
|
|
.Fn 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)"
|
|
.Ft void
|
|
.Fn pmf_device_deregister "device_t dev"
|
|
.Ft bool
|
|
.Fn pmf_device_suspend "device_t dev" "const pmf_qual_t *qual"
|
|
.Ft bool
|
|
.Fn pmf_device_resume "device_t dev" "const pmf_qual_t *qual"
|
|
.Ft bool
|
|
.Fn pmf_device_recursive_suspend "device_t dev" "const pmf_qual_t *qual"
|
|
.Ft bool
|
|
.Fn pmf_device_recursive_resume "device_t dev" "const pmf_qual_t *qual"
|
|
.Ft bool
|
|
.Fn pmf_device_subtree_resume "device_t dev" "const pmf_qual_t *qual"
|
|
.Ft void
|
|
.Fn pmf_class_network_register "device_t dev" "struct ifnet *ifp"
|
|
.Ft bool
|
|
.Fn pmf_class_input_register "device_t dev"
|
|
.Ft bool
|
|
.Fn pmf_class_display_register "device_t dev"
|
|
.Ft bool
|
|
.Fn pmf_system_suspend "const pmf_qual_t *qual"
|
|
.Ft bool
|
|
.Fn pmf_system_resume "const pmf_qual_t *qual"
|
|
.Ft void
|
|
.Fn pmf_system_shutdown "int"
|
|
.Ft bool
|
|
.Fn pmf_event_register "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global"
|
|
.Ft void
|
|
.Fn pmf_event_deregister "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global"
|
|
.Ft bool
|
|
.Fn pmf_event_inject "device_t dev" "pmf_generic_event_t ev"
|
|
.Ft bool
|
|
.Fn pmf_set_platform "const char *key" "const char *value"
|
|
.Ft const char *
|
|
.Fn pmf_get_platform "const char *key"
|
|
.Sh DESCRIPTION
|
|
The machine-independent
|
|
.Nm
|
|
framework provides power management and inter-driver messaging support
|
|
for device drivers.
|
|
.Sh DATA TYPES
|
|
Drivers for devices implementing
|
|
.Nm
|
|
may make use of the following data type:
|
|
.Bl -tag -width compact
|
|
.It Fa pmf_qual_t
|
|
An opaque aggregate of qualifications on a
|
|
.Nm
|
|
suspend or resume call.
|
|
.It Fa 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:
|
|
.Bl -item -compact -offset indent
|
|
.It
|
|
.Dv PMFE_DISPLAY_ON
|
|
.It
|
|
.Dv PMFE_DISPLAY_REDUCED
|
|
.It
|
|
.Dv PMFE_DISPLAY_STANDBY
|
|
.It
|
|
.Dv PMFE_DISPLAY_SUSPEND
|
|
.It
|
|
.Dv PMFE_DISPLAY_OFF
|
|
.It
|
|
.Dv PMFE_DISPLAY_BRIGHTNESS_UP
|
|
.It
|
|
.Dv PMFE_DISPLAY_BRIGHTNESS_DOWN
|
|
.It
|
|
.Dv PMFE_AUDIO_VOLUME_UP
|
|
.It
|
|
.Dv PMFE_AUDIO_VOLUME_DOWN
|
|
.It
|
|
.Dv PMFE_AUDIO_VOLUME_TOGGLE
|
|
.It
|
|
.Dv PMFE_CHASSIS_LID_CLOSE
|
|
.It
|
|
.Dv PMFE_CHASSIS_LID_OPEN
|
|
.El
|
|
.El
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn pmf_device_register "dev" "suspend" "resume"
|
|
Register a device with the power management framework.
|
|
The
|
|
.Fa suspend
|
|
and
|
|
.Fa resume
|
|
functions are passed
|
|
.Fa dev
|
|
and a
|
|
.Fa pmf_qual_t ,
|
|
and will be called when the system state changes;
|
|
they should return
|
|
.Dv true
|
|
on success and
|
|
.Dv false
|
|
on failure.
|
|
If either
|
|
.Fa suspend
|
|
or
|
|
.Fa resume
|
|
is
|
|
.Dv 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.
|
|
.Pp
|
|
.Fn pmf_device_register
|
|
always returns true.
|
|
Callers should ignore the return value.
|
|
.It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown"
|
|
Like
|
|
.Fn pmf_device_register ,
|
|
but additionally registers a shutdown handler.
|
|
During system shutdown,
|
|
.Fn pmf_system_shutdown
|
|
calls
|
|
.Fa shutdown
|
|
on
|
|
.Fa dev
|
|
with the
|
|
.Xr reboot 2
|
|
.Dq howto
|
|
in the second argument.
|
|
.Fa shutdown
|
|
should return
|
|
.Dv true
|
|
on success and
|
|
.Dv false
|
|
on failure.
|
|
.Pp
|
|
.Fn pmf_device_register1
|
|
always returns true.
|
|
Callers should ignore the return value.
|
|
.It Fn pmf_device_deregister "dev"
|
|
Deregister a device with the power management framework.
|
|
.It Fn 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.
|
|
.It Fn 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.
|
|
.It Fn pmf_device_recursive_suspend "dev" "qual"
|
|
As
|
|
.Fn pmf_device_suspend ,
|
|
but ensures that all child devices of
|
|
.Fa dev
|
|
are suspended.
|
|
.It Fn pmf_device_recursive_resume "dev" "qual"
|
|
As
|
|
.Fn pmf_device_resume ,
|
|
but ensures that all parent devices of
|
|
.Fa dev
|
|
are resumed.
|
|
.It Fn pmf_device_subtree_resume "dev" "qual"
|
|
As
|
|
.Fn pmf_device_resume ,
|
|
but ensures that all child devices of
|
|
.Fa dev
|
|
are resumed.
|
|
.It Fn pmf_class_network_register "dev" "ifp"
|
|
Register a device with the power management framework as a network-class
|
|
device.
|
|
.It Fn pmf_class_input_register "dev"
|
|
Register a device with the power management framework as an input-class
|
|
device.
|
|
.It Fn pmf_class_display_register "dev"
|
|
Register a device with the power management framework as a display-class
|
|
device.
|
|
.It Fn 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.
|
|
.It Fn 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.
|
|
.It Fn 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
|
|
.Xr reboot 2
|
|
.Dq howto
|
|
argument.
|
|
This function ignores the presence of attached drivers that do not support the
|
|
power management framework.
|
|
.It Fn pmf_event_register "dev" "ev" "handler" "global"
|
|
Register the callback
|
|
.Fa handler
|
|
to be called whenever an
|
|
.Fa ev
|
|
event is triggered.
|
|
If
|
|
.Fa global
|
|
is
|
|
.Dv true ,
|
|
.Fa handler
|
|
accepts anonymous events from
|
|
.Fn pmf_event_inject .
|
|
.It Fn pmf_event_deregister "dev" "ev" "handler" "global"
|
|
Deregister the callback previously registered with
|
|
.Fn pmf_event_register .
|
|
.It Fn pmf_event_inject "dev" "ev"
|
|
Inject an inter-driver message into the message queue.
|
|
If
|
|
.Fa dev
|
|
is
|
|
.Dv 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
|
|
.Fa dev .
|
|
.It Fn pmf_set_platform "key" "value"
|
|
Insert a name-value pair into the platform information database.
|
|
.It Fn pmf_get_platform "key"
|
|
Retrieve the value for
|
|
.Fa key
|
|
from the platform information database.
|
|
Returns
|
|
.Dv NULL
|
|
if the key is not present.
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
The power management framework is implemented within the files
|
|
.Pa sys/sys/pmf.h ,
|
|
.Pa sys/sys/device.h ,
|
|
.Pa sys/kern/kern_pmf.c ,
|
|
and
|
|
.Pa sys/kern/subr_autoconf.c .
|
|
.Sh SEE ALSO
|
|
.Xr autoconf 9 ,
|
|
.Xr driver 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
framework appeared in
|
|
.Nx 5.0 .
|
|
.Sh AUTHORS
|
|
.An Jared D. McNeill Aq Mt jmcneill@NetBSD.org
|
|
.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org
|
|
.Sh BUGS
|
|
.Fn pmf_device_register
|
|
and
|
|
.Fn pmf_device_register1
|
|
never fail and should return void, but until all callers are updated to
|
|
ignore the return value, they must continue to return bool:
|
|
.Lk "https://gnats.NetBSD.org/57575" "PR kern/57575"
|