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