1.\" $NetBSD: pmf.9,v 1.7 2008/03/29 14:12:59 jmcneill Exp $ 2.\" 3.\" Copyright (c) 2007 Jared D. McNeill <jmcneill@invisible.ca> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Jared D. McNeill. 17.\" 4. Neither the name of The NetBSD Foundation nor the names of its 18.\" contributors may be used to endorse or promote products derived 19.\" from this software without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 23.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 24.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 25.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31.\" POSSIBILITY OF SUCH DAMAGE. 32.\" 33.Dd March 29, 2008 34.Dt PMF 9 35.Os 36.Sh NAME 37.Nm PMF , 38.Nm pmf_device_register , 39.Nm pmf_device_deregister , 40.Nm pmf_device_suspend , 41.Nm pmf_device_resume , 42.Nm pmf_device_recursive_suspend , 43.Nm pmf_device_recursive_resume , 44.Nm pmf_device_resume_subtree , 45.Nm pmf_class_network_register , 46.Nm pmf_class_input_register , 47.Nm pmf_class_display_register , 48.Nm pmf_system_suspend , 49.Nm pmf_system_resume , 50.Nm pmf_system_shutdown , 51.Nm pmf_event_register , 52.Nm pmf_event_deregister , 53.Nm pmf_event_inject , 54.Nm pmf_set_platform , 55.Nm pmf_get_platform 56.Nd power management and inter-driver messaging framework 57.Sh SYNOPSIS 58.In sys/device.h 59.Ft bool 60.Fn pmf_device_register "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)" 61.Fn pmf_device_register1 "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)" "bool (*shutdown)(device_t dev, int how)" 62.Ft void 63.Fn pmf_device_deregister "device_t dev" 64.Ft bool 65.Fn pmf_device_suspend "device_t dev" 66.Ft bool 67.Fn pmf_device_resume "device_t dev" 68.Ft bool 69.Fn pmf_device_recursive_suspend "device_t dev" 70.Ft bool 71.Fn pmf_device_recursive_resume "device_t dev" 72.Ft bool 73.Fn pmf_device_resume_subtree "device_t dev" 74.Ft void 75.Fn pmf_class_network_register "device_t dev" "struct ifnet *ifp" 76.Ft bool 77.Fn pmf_class_input_register "device_t dev" 78.Ft bool 79.Fn pmf_class_display_register "device_t dev" 80.Ft bool 81.Fn pmf_system_suspend "void" 82.Ft bool 83.Fn pmf_system_resume "void" 84.Ft void 85.Fn pmf_system_shutdown "int" 86.Ft bool 87.Fn pmf_event_register "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global" 88.Ft void 89.Fn pmf_event_deregister "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global" 90.Ft bool 91.Fn pmf_event_inject "device_t dev" "pmf_generic_event_t ev" 92.Ft bool 93.Fn pmf_set_platform "const char *key" "const char *value" 94.Ft const char * 95.Fn pmf_get_platform "const char *key" 96.Sh DESCRIPTION 97The machine-independent 98.Nm 99framework provides power management and inter-driver messaging support 100for device drivers. 101.Sh DATA TYPES 102Drivers for devices implementing 103.Nm 104may make use of the following data type: 105.Bl -tag -width compact 106.It Fa pmf_generic_event_t 107A device driver can register as a listener for specific events, or inject 108events into the message queue. 109The following message types are defined: 110.Bl -item -compact -offset indent 111.It 112.Dv PMFE_DISPLAY_ON 113.It 114.Dv PMFE_DISPLAY_REDUCED 115.It 116.Dv PMFE_DISPLAY_STANDBY 117.It 118.Dv PMFE_DISPLAY_SUSPEND 119.It 120.Dv PMFE_DISPLAY_OFF 121.It 122.Dv PMFE_DISPLAY_BRIGHTNESS_UP 123.It 124.Dv PMFE_DISPLAY_BRIGHTNESS_DOWN 125.It 126.Dv PMFE_AUDIO_VOLUME_DOWN 127.It 128.Dv PMFE_AUDIO_VOLUME_TOGGLE 129.It 130.Dv PMFE_CHASSIS_LID_CLOSE 131.It 132.Dv PMFE_CHASSIS_LID_OPEN 133.El 134.El 135.Sh FUNCTIONS 136.Bl -tag -width compact 137.It Fn pmf_device_register "dev" "suspend" "resume" 138Register a device with the power management framework. If either 139.Fa suspend 140or 141.Fa resume 142is 143.Dv NULL 144then it is assumed that device state does not need to be captured and 145resumed on a power transition. Bus and class-level power management 146will still be performed. Returns 147.Dv false 148if there was an error. 149.It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown" 150Like pmf_device_register, but additionally registers a shutdown handler. 151.It Fn pmf_device_deregister "dev" 152Deregister a device with the power management framework. 153.It Fn pmf_device_suspend "dev" 154Suspend a device by first calling the class suspend handler, followed by 155the driver suspend handler, and finally the bus suspend handler. 156.It Fn pmf_device_resume "dev" 157Resume a device by first calling the bus resume handler, followed by the 158driver resume handler, and finally the class resume handler. 159.It Fn pmf_device_recursive_suspend "dev" 160As 161.Fn pmf_device_suspend , 162but ensures that all child devices of 163.Fa dev 164are suspended. 165.It Fn pmf_device_recursive_resume "dev" 166As 167.Fn pmf_device_resume , 168but ensures that all parent devices of 169.Fa dev 170are resumed. 171.It Fn pmf_device_resume_subtree "dev" 172As 173.Fn pmf_device_resume , 174but ensures that all child devices of 175.Fa dev 176are resumed. 177.It Fn pmf_class_network_register "dev" "ifp" 178Register a device with the power management framework as a network-class 179device. 180.It Fn pmf_class_input_register "dev" 181Register a device with the power management framework as an input-class 182device. 183.It Fn pmf_class_display_register "dev" 184Register a device with the power management framework as a display-class 185device. 186.It Fn pmf_system_suspend "void" 187Suspend all attached devices. Devices are suspended by traversing the 188autoconfiguration tree beginning with the leaf nodes. 189This function will fail if any attached drivers do not support the power 190management framework. 191.It Fn pmf_system_resume "void" 192Resume all attached devices. Devices are resumed by traversing the 193autoconfiguration tree beginning with devices that do not have a parent. 194This function will fail if any attached drivers do not support the power 195management framework. 196.It Fn pmf_system_shutdown "int" 197Shutdown all attached devices. Devices are shut down by traversing the 198autoconfiguration tree beginning with the leaf nodes. 199The integer argument is passed to the driver shutdown functions. 200It should contain the reboot(2) 201.Dq howto 202argument. 203This function ignores the presence of attached drivers that do not support the 204power management framework. 205.It Fn pmf_event_register "dev" "ev" "handler" "global" 206Register the callback 207.Fa handler 208to be called whenever an 209.Fa ev 210event is triggered. If 211.Fa global 212is 213.Dv true , 214.Fa handler 215accepts anonymous events from 216.Fn pmf_event_inject . 217.It Fn pmf_event_deregister "dev" "ev" "handler" "global" 218Deregister the callback previously registered with 219.Fn pmf_event_register . 220.It Fn pmf_event_inject "dev" "ev" 221Inject an inter-driver message into the message queue. If 222.Fa dev 223is 224.Dv NULL , 225the event is considered to be anonymous and one or more drivers 226may handle this event, otherwise the event is delivered directly to 227the callback registered by 228.Fa dev . 229.It Fn pmf_set_platform "key" "value" 230Insert a name-value pair into the platform information database. 231.It Fn pmf_get_platform "key" 232Retrieve the value for 233.Fa key 234from the platform information database. Returns 235.Dv NULL 236if the key is not present. 237.El 238.Sh CODE REFERENCES 239This section describes places within the 240.Nx 241source tree where actual code implementing or using the power management 242framework can be found. 243All pathnames are relative to 244.Pa /usr/src . 245.Pp 246The power management framework is implemented within the files 247.Pa sys/sys/pmf.h , 248.Pa sys/sys/device.h , 249.Pa sys/kern/kern_pmf.c , 250and 251.Pa sys/kern/subr_autoconf.c . 252.Sh SEE ALSO 253.Xr autoconf 9 , 254.Xr driver 9 255.Sh HISTORY 256The 257.Nm 258framework appeared in 259.Nx 5.0 . 260.Sh AUTHORS 261.An Jared D. McNeill Aq jmcneill@NetBSD.org 262.An Joerg Sonnenberger Aq joerg@NetBSD.org 263