1.\" $NetBSD: pmf.9,v 1.22 2014/03/18 18:20:40 riastradh 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 April 2, 2012 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, const pmf_qual_t *qual)" "bool (*resume)(device_t dev, const pmf_qual_t *qual)" 56.Ft bool 57.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)" 58.Ft void 59.Fn pmf_device_deregister "device_t dev" 60.Ft bool 61.Fn pmf_device_suspend "device_t dev" "const pmf_qual_t *qual" 62.Ft bool 63.Fn pmf_device_resume "device_t dev" "const pmf_qual_t *qual" 64.Ft bool 65.Fn pmf_device_recursive_suspend "device_t dev" "const pmf_qual_t *qual" 66.Ft bool 67.Fn pmf_device_recursive_resume "device_t dev" "const pmf_qual_t *qual" 68.Ft bool 69.Fn pmf_device_subtree_resume "device_t dev" "const pmf_qual_t *qual" 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 "const pmf_qual_t *qual" 78.Ft bool 79.Fn pmf_system_resume "const pmf_qual_t *qual" 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_qual_t 103An opaque aggregate of qualifications on a 104.Nm 105suspend or resume call. 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_UP 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. 141The 142.Fa suspend 143and 144.Fa resume 145functions are passed 146.Fa dev 147and a 148.Fa pmf_qual_t , 149and will be called when the system state changes; 150they should return 151.Dv true 152on success and 153.Dv false 154on failure. 155If either 156.Fa suspend 157or 158.Fa resume 159is 160.Dv NULL 161then it is assumed that device state does not need to be captured and 162resumed on a power transition. 163Bus and class-level power management will still be performed. 164Returns 165.Dv false 166if there was an error. 167.It Fn pmf_device_register1 "dev" "suspend" "resume" "shutdown" 168Like 169.Fn pmf_device_register , 170but additionally registers a shutdown handler. 171During system shutdown, 172.Fn pmf_system_shutdown 173calls 174.Fa shutdown 175on 176.Fa dev 177with the 178.Xr reboot 2 179.Dq howto 180in the second argument. 181.Fa shutdown 182should return 183.Dv true 184on success and 185.Dv false 186on failure. 187.It Fn pmf_device_deregister "dev" 188Deregister a device with the power management framework. 189.It Fn pmf_device_suspend "dev" "qual" 190Suspend a device by first calling the class suspend handler, followed by 191the driver suspend handler, and finally the bus suspend handler. 192.It Fn pmf_device_resume "dev" "qual" 193Resume a device by first calling the bus resume handler, followed by the 194driver resume handler, and finally the class resume handler. 195.It Fn pmf_device_recursive_suspend "dev" "qual" 196As 197.Fn pmf_device_suspend , 198but ensures that all child devices of 199.Fa dev 200are suspended. 201.It Fn pmf_device_recursive_resume "dev" "qual" 202As 203.Fn pmf_device_resume , 204but ensures that all parent devices of 205.Fa dev 206are resumed. 207.It Fn pmf_device_subtree_resume "dev" "qual" 208As 209.Fn pmf_device_resume , 210but ensures that all child devices of 211.Fa dev 212are resumed. 213.It Fn pmf_class_network_register "dev" "ifp" 214Register a device with the power management framework as a network-class 215device. 216.It Fn pmf_class_input_register "dev" 217Register a device with the power management framework as an input-class 218device. 219.It Fn pmf_class_display_register "dev" 220Register a device with the power management framework as a display-class 221device. 222.It Fn pmf_system_suspend "qual" 223Suspend all attached devices. 224Devices are suspended by traversing the autoconfiguration tree 225beginning with the leaf nodes. 226This function will fail if any attached drivers do not support the power 227management framework. 228.It Fn pmf_system_resume "qual" 229Resume all attached devices. 230Devices are resumed by traversing the 231autoconfiguration tree beginning with devices that do not have a parent. 232This function will fail if any attached drivers do not support the power 233management framework. 234.It Fn pmf_system_shutdown "int" 235Shutdown all attached devices. 236Devices are shut down by traversing the 237autoconfiguration tree beginning with the leaf nodes. 238The integer argument is passed to the driver shutdown functions. 239It should contain the 240.Xr reboot 2 241.Dq howto 242argument. 243This function ignores the presence of attached drivers that do not support the 244power management framework. 245.It Fn pmf_event_register "dev" "ev" "handler" "global" 246Register the callback 247.Fa handler 248to be called whenever an 249.Fa ev 250event is triggered. 251If 252.Fa global 253is 254.Dv true , 255.Fa handler 256accepts anonymous events from 257.Fn pmf_event_inject . 258.It Fn pmf_event_deregister "dev" "ev" "handler" "global" 259Deregister the callback previously registered with 260.Fn pmf_event_register . 261.It Fn pmf_event_inject "dev" "ev" 262Inject an inter-driver message into the message queue. 263If 264.Fa dev 265is 266.Dv NULL , 267the event is considered to be anonymous and one or more drivers 268may handle this event, otherwise the event is delivered directly to 269the callback registered by 270.Fa dev . 271.It Fn pmf_set_platform "key" "value" 272Insert a name-value pair into the platform information database. 273.It Fn pmf_get_platform "key" 274Retrieve the value for 275.Fa key 276from the platform information database. 277Returns 278.Dv NULL 279if the key is not present. 280.El 281.Sh CODE REFERENCES 282The power management framework is implemented within the files 283.Pa sys/sys/pmf.h , 284.Pa sys/sys/device.h , 285.Pa sys/kern/kern_pmf.c , 286and 287.Pa sys/kern/subr_autoconf.c . 288.Sh SEE ALSO 289.Xr autoconf 9 , 290.Xr driver 9 291.Sh HISTORY 292The 293.Nm 294framework appeared in 295.Nx 5.0 . 296.Sh AUTHORS 297.An Jared D. McNeill Aq Mt jmcneill@NetBSD.org 298.An Joerg Sonnenberger Aq Mt joerg@NetBSD.org 299