path: root/static/netbsd/man9/pmf.9

.\" $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"