.\" $NetBSD: pmf.9,v 1.1 2007/12/09 20:37:43 jmcneill Exp $ .\" .\" Copyright (c) 2007 Jared D. McNeill .\" 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Jared D. McNeill. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" 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 December 8, 2007 .Dt PMF 9 .Os .Sh NAME .Nm PMF , .Nm pmf_device_register , .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 void .Fn pmf_device_register "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)" .Ft void .Fn pmf_device_deregister "device_t dev" .Ft bool .Fn pmf_device_suspend "device_t dev" .Ft bool .Fn pmf_device_resume "device_t dev" .Ft bool .Fn pmf_device_recursive_suspend "device_t dev" .Ft bool .Fn pmf_device_recursive_resume "device_t dev" .Ft bool .Fn pmf_device_resume_subtree "device_t dev" .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 "void" .Ft bool .Fn pmf_system_resume "void" .Ft void .Fn pmf_system_shutdown "void" .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_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: .Bd -literal 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 .Ed .El .Sh FUNCTIONS .Bl -tag -width compact .It Fn pmf_device_register "dev" "suspend" "resume" Register a device with the power management framework. 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. .It Fn pmf_device_deregister "dev" Deregister a device with the power management framework. .It Fn 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. .It Fn 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. .It Fn pmf_device_recursive_suspend "dev" As .Fn pmf_device_suspend , but ensures that all child devices of .Fa dev are suspended. .It Fn pmf_device_recursive_resume "dev" As .Fn pmf_device_resume , but ensures that all parent devices of .Fa dev are resumed. .It Fn pmf_device_resume_subtree "dev" 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 "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. .It Fn 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. .It Fn pmf_system_shutdown "void" As .Fn pmf_system_suspend , but 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 This section describes places within the .Nx source tree where actual code implementing or using the power management framework can be found. All pathnames are relative to .Pa /usr/src . .Pp The power management framework is implemented within the files .Pa sys/pmf.h , .Pa 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 jmcneill@NetBSD.org .An Joerg Sonnenberger Aq joerg@NetBSD.org