diff options
Diffstat (limited to 'static/netbsd/man9/pmf.9')
| -rw-r--r-- | static/netbsd/man9/pmf.9 | 310 |
1 files changed, 310 insertions, 0 deletions
diff --git a/static/netbsd/man9/pmf.9 b/static/netbsd/man9/pmf.9 new file mode 100644 index 00000000..a20f5dc3 --- /dev/null +++ b/static/netbsd/man9/pmf.9 @@ -0,0 +1,310 @@ +.\" $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" |