1.\" $NetBSD: pmf.9,v 1.9 2009/05/10 12:46:41 wiz 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 May 10, 2009 34.Dt PMF 9 35.Os 36.Sh NAME 37.Nm PMF , 38.Nm pmf_device_register , 39.Nm pmf_device_register1 , 40.Nm pmf_device_deregister , 41.Nm pmf_device_suspend , 42.Nm pmf_device_resume , 43.Nm pmf_device_recursive_suspend , 44.Nm pmf_device_recursive_resume , 45.Nm pmf_device_resume_subtree , 46.Nm pmf_class_network_register , 47.Nm pmf_class_input_register , 48.Nm pmf_class_display_register , 49.Nm pmf_system_suspend , 50.Nm pmf_system_resume , 51.Nm pmf_system_shutdown , 52.Nm pmf_event_register , 53.Nm pmf_event_deregister , 54.Nm pmf_event_inject , 55.Nm pmf_set_platform , 56.Nm pmf_get_platform 57.Nd power management and inter-driver messaging framework 58.Sh SYNOPSIS 59.In sys/device.h 60.Ft bool 61.Fn pmf_device_register "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)" 62.Ft bool 63.Fn pmf_device_register1 "device_t dev" "bool (*suspend)(device_t dev)" "bool (*resume)(device_t dev)" "bool (*shutdown)(device_t dev, int how)" 64.Ft void 65.Fn pmf_device_deregister "device_t dev" 66.Ft bool 67.Fn pmf_device_suspend "device_t dev" 68.Ft bool 69.Fn pmf_device_resume "device_t dev" 70.Ft bool 71.Fn pmf_device_recursive_suspend "device_t dev" 72.Ft bool 73.Fn pmf_device_recursive_resume "device_t dev" 74.Ft bool 75.Fn pmf_device_resume_subtree "device_t dev" 76.Ft void 77.Fn pmf_class_network_register "device_t dev" "struct ifnet *ifp" 78.Ft bool 79.Fn pmf_class_input_register "device_t dev" 80.Ft bool 81.Fn pmf_class_display_register "device_t dev" 82.Ft bool 83.Fn pmf_system_suspend "void" 84.Ft bool 85.Fn pmf_system_resume "void" 86.Ft void 87.Fn pmf_system_shutdown "int" 88.Ft bool 89.Fn pmf_event_register "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global" 90.Ft void 91.Fn pmf_event_deregister "device_t dev" "pmf_generic_event_t ev" "void (*handler)(device_t dev)" "bool global" 92.Ft bool 93.Fn pmf_event_inject "device_t dev" "pmf_generic_event_t ev" 94.Ft bool 95.Fn pmf_set_platform "const char *key" "const char *value" 96.Ft const char * 97.Fn pmf_get_platform "const char *key" 98.Sh DESCRIPTION 99The machine-independent 100.Nm 101framework provides power management and inter-driver messaging support 102for device drivers. 103.Sh DATA TYPES 104Drivers for devices implementing 105.Nm 106may make use of the following data type: 107.Bl -tag -width compact 108.It Fa pmf_generic_event_t 109A device driver can register as a listener for specific events, or inject 110events into the message queue. 111The following message types are defined: 112.Bl -item -compact -offset indent 113.It 114.Dv PMFE_DISPLAY_ON 115.It 116.Dv PMFE_DISPLAY_REDUCED 117.It 118.Dv PMFE_DISPLAY_STANDBY 119.It 120.Dv PMFE_DISPLAY_SUSPEND 121.It 122.Dv PMFE_DISPLAY_OFF 123.It 124.Dv PMFE_DISPLAY_BRIGHTNESS_UP 125.It 126.Dv PMFE_DISPLAY_BRIGHTNESS_DOWN 127.It 128.Dv PMFE_AUDIO_VOLUME_DOWN 129.It 130.Dv PMFE_AUDIO_VOLUME_TOGGLE 131.It 132.Dv PMFE_CHASSIS_LID_CLOSE 133.It 134.Dv PMFE_CHASSIS_LID_OPEN 135.El 136.El 137.Sh FUNCTIONS 138.Bl -tag -width compact 139.It Fn pmf_device_register "dev" "suspend" "resume" 140Register a device with the power management framework. 141If either 142.Fa suspend 143or 144.Fa resume 145is 146.Dv NULL 147then it is assumed that device state does not need to be captured and 148resumed on a power transition. 149Bus and class-level power management will still be performed. 150Returns 151.Dv false 152if there was an error. 153.It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown" 154Like pmf_device_register, but additionally registers a shutdown handler. 155.It Fn pmf_device_deregister "dev" 156Deregister a device with the power management framework. 157.It Fn pmf_device_suspend "dev" 158Suspend a device by first calling the class suspend handler, followed by 159the driver suspend handler, and finally the bus suspend handler. 160.It Fn pmf_device_resume "dev" 161Resume a device by first calling the bus resume handler, followed by the 162driver resume handler, and finally the class resume handler. 163.It Fn pmf_device_recursive_suspend "dev" 164As 165.Fn pmf_device_suspend , 166but ensures that all child devices of 167.Fa dev 168are suspended. 169.It Fn pmf_device_recursive_resume "dev" 170As 171.Fn pmf_device_resume , 172but ensures that all parent devices of 173.Fa dev 174are resumed. 175.It Fn pmf_device_resume_subtree "dev" 176As 177.Fn pmf_device_resume , 178but ensures that all child devices of 179.Fa dev 180are resumed. 181.It Fn pmf_class_network_register "dev" "ifp" 182Register a device with the power management framework as a network-class 183device. 184.It Fn pmf_class_input_register "dev" 185Register a device with the power management framework as an input-class 186device. 187.It Fn pmf_class_display_register "dev" 188Register a device with the power management framework as a display-class 189device. 190.It Fn pmf_system_suspend "void" 191Suspend all attached devices. 192Devices are suspended by traversing the 193autoconfiguration tree beginning with the leaf nodes. 194This function will fail if any attached drivers do not support the power 195management framework. 196.It Fn pmf_system_resume "void" 197Resume all attached devices. 198Devices are resumed by traversing the 199autoconfiguration tree beginning with devices that do not have a parent. 200This function will fail if any attached drivers do not support the power 201management framework. 202.It Fn pmf_system_shutdown "int" 203Shutdown all attached devices. 204Devices are shut down by traversing the 205autoconfiguration tree beginning with the leaf nodes. 206The integer argument is passed to the driver shutdown functions. 207It should contain the 208.Xr reboot 2 209.Dq howto 210argument. 211This function ignores the presence of attached drivers that do not support the 212power management framework. 213.It Fn pmf_event_register "dev" "ev" "handler" "global" 214Register the callback 215.Fa handler 216to be called whenever an 217.Fa ev 218event is triggered. 219If 220.Fa global 221is 222.Dv true , 223.Fa handler 224accepts anonymous events from 225.Fn pmf_event_inject . 226.It Fn pmf_event_deregister "dev" "ev" "handler" "global" 227Deregister the callback previously registered with 228.Fn pmf_event_register . 229.It Fn pmf_event_inject "dev" "ev" 230Inject an inter-driver message into the message queue. 231If 232.Fa dev 233is 234.Dv NULL , 235the event is considered to be anonymous and one or more drivers 236may handle this event, otherwise the event is delivered directly to 237the callback registered by 238.Fa dev . 239.It Fn pmf_set_platform "key" "value" 240Insert a name-value pair into the platform information database. 241.It Fn pmf_get_platform "key" 242Retrieve the value for 243.Fa key 244from the platform information database. 245Returns 246.Dv NULL 247if the key is not present. 248.El 249.Sh CODE REFERENCES 250This section describes places within the 251.Nx 252source tree where actual code implementing or using the power management 253framework can be found. 254All pathnames are relative to 255.Pa /usr/src . 256.Pp 257The power management framework is implemented within the files 258.Pa sys/sys/pmf.h , 259.Pa sys/sys/device.h , 260.Pa sys/kern/kern_pmf.c , 261and 262.Pa sys/kern/subr_autoconf.c . 263.Sh SEE ALSO 264.Xr autoconf 9 , 265.Xr driver 9 266.Sh HISTORY 267The 268.Nm 269framework appeared in 270.Nx 5.0 . 271.Sh AUTHORS 272.An Jared D. McNeill Aq jmcneill@NetBSD.org 273.An Joerg Sonnenberger Aq joerg@NetBSD.org 274